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About This Book 





This guide describes how to install the SilverStream eXtend Application Server and configure 
databases for use with the SilverStream server. 


Audience 


This guide is for users responsible for installing and configuring the SilverStream eXtend 
Application Server for both development and production environments. 


Organization 


This section provides a brief summary of each chapter. 





Chapter 


Description 





Chapter 1, “Introduction” 


An overview of the SilverStream server and the 
SilverStream installation program 





Chapter 2, “Installing the 
SilverStream Server on 
Windows” 


How to install the SilverStream server on Windows 
platforms 





Chapter 3, “Installing the 
SilverStream Server on 
UNIX” 


How to install the SilverStream server on UNIX and Linux 
platforms 





Chapter 4, “Installing 
Enterprise Data Connectors” 


How to install and configure the SilverStream Enterprise 
Data Connectors (EDCs) 





Chapter 5, “Configuring 
Cloudscape Databases” 


How to set up IBM Cloudscape databases for use within 
the SilverStream environment 





Chapter 6, “Configuring DB2 
Databases” 


How to set up IBM DB2 databases for use within the 
SilverStream environment 





Chapter 7, “Configuring 
Informix Databases” 








How to set up IBM Informix databases for use within the 
SilverStream environment 
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Chapter Description 

Chapter 8, “Configuring How to set up Microsoft Access databases for use within 
Microsoft Access Databases” | the SilverStream environment 

Chapter 9, “Configuring How to set up Microsoft SQL Server databases for use 
Microsoft SQL Server within the SilverStream environment 

Databases” 

Chapter 10, “Configuring How to set up Oracle databases for use within the 
Oracle Databases” SilverStream environment 

Chapter 11, “Configuring How to set up Sybase Adaptive Server Anywhere 
Sybase Adaptive Server databases for use within the SilverStream environment 
Anywhere Databases” 

Chapter 12, “Configuring How to set up Sybase Adaptive Server Enterprise 
Sybase Adaptive Server databases for use within the SilverStream environment 
Enterprise Databases” 

Appendix A, “Creating How to create ODBC data source entries on Windows 
ODBC Data Sources” 

















i 


Introduction 





This chapter presents an overview of the SilverStream eXtend Application Server and the 
SilverStream server installation program. The SilverStream server installation program is self- 
documenting—that is, it includes documentation in the installation screens. There are some 
decisions you should make before installing the SilverStream server. This chapter helps you 
make those decisions. 


The chapter includes the following sections: 


(AA) 


Application server configurations 
About the installation program 
Installation decisions 

Migrating to Version 4 
Contacting Technical Support 


For the latest information on hardware and software requirements and supported 


databases, see the Release Notes. In Windows, you can access the Release Notes from the 
SilverStream eXtend program group or from the server’s Core Help. 


Application server configurations 


The SilverStream server is both a development and deployment product. It is available in these 
configurations: 


SilverStream Developer Edition (SDE) is configured for use by a single developer 
writing J2EE/Web Service applications using SilverStream eXtend Workbench. It comes 
with two development databases, Adaptive Server Anywhere and Cloudscape. SDE is 
meant for development and testing, but does not support any but the smallest deployments 
(it is limited to 8 concurrent sessions). 


SilverStream Classic Edition (SCE) is equivalent to SDE, plus it includes a copy of the 
classic SilverStream Designer. This edition is for developers maintaining classic 
SilverStream applications (that is, applications consisting of SilverStream pages, forms, 
and business objects). 
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About the 


SilverStream Professional Edition (SPE) targets deployments that need high 
performance and scalability but do not have a strict availability requirement and can 
tolerate occasional downtime. This edition is licensed per CPU with no limit on 
concurrent sessions. SPE does not support clustering and therefore does not tolerate 
machine failure. You can increase the scalability of your applications by adding more 
processors to the server machine. 


SilverStream Enterprise Edition (SEE) targets deployments that require both scalability 
and reliability. Like SPE, this edition is licensed by CPU. Unlike SPE, SEE supports 
clustering across multiple machines. Clustering provides high availability of applications 
by masking individual hardware and software failures. 


installation program 


The Windows NT installation program is a wizard-based InstallShield program that allows 
you to select and install the various components of the SilverStream server, tools, 
documentation, and sample applications. This program also provides an interface to the 
Fulcrum SearchServer and Sybase Adaptive Server Anywhere installation programs. 


The UNIX installation script install.sh starts a PERL script to install and configure the 
SilverStream eXtend Application Server on UNIX and Linux. 


The SilverStream server installation performs the following tasks: 


Copies files from the distribution CD to the specified directories. 


Asks which database you want to use for the SilverMaster (see “Choosing a database for 
SilverMaster” on page 3). 

Executes the SilverMasterInit program. 

The SilverMasterInit program creates the SilverMaster database tables and uploads the 
SilverStream resources needed to support both the design-time and runtime environments 
into the SilverMaster database. 

In Windows, creates a SilverStream eXtend>AppServer program group with entries for 
the SilverStream server, SilverStream Management Console (SMC), SilverStream Help, 
Release Notes, and SilverStream Designer (Classic Edition only). 

Creates Windows registry keys 
(HKEY_LOCAL_MACHINE\SOFTWARE\SilverStream Software 

Inc.\eXtend\A ppServer) (or creates a SilverStream proprietary registry on UNIX). 
Asks for a license key to be applied to the SilverStream server. The license key is 
uploaded and stored in the SilverMaster database. 
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Installation decisions 


Before you install the SilverStream server, you should decide the following: 


Do you want to install the Fulcrum SearchServer engine? 
The Fulcrum SearchServer engine allows you to use full-text search in applications. 


NOTE The use of Fulcrum SearchServer with the SilverStream server is deprecated 
starting in Version 4. It will be removed in Version 5 of the application server. 
To enable full text search (and other advanced searching techniques) in your 
applications, we recommend that you use the facilities provided by the Search 
subsystem in eXtend Director. See the Director documentation for details. 


Do you want to install Sybase Adaptive Server Anywhere? 


The classic sample databases shipped with the SilverStream server are Sybase Adaptive 
Server Anywhere databases. You must have Sybase Adaptive Server Anywhere to access 
these databases (Adaptive Server Anywhere is provided with the Developer and Classic 
editions only). 


What kind of install do you want to perform? 

You can install the full SilverStream product or just specified components. 

LL) For more information, see “Choosing the installation type” on page 4. 

Which database will you use for your SilverMaster? 

The SilverStream server requires that one database be set up as the SilverMaster database. 


(J For more information about SilverMaster, see the next section. 


Choosing a database for SilverMaster 


The SilverMaster database catalog is a database used by the SilverStream server. There is one 
SilverMaster catalog for each SilverStream server or SilverStream cluster. The SilverMaster 
keeps track of all of the application databases used by the SilverStream server and also holds the 
SilverStream system tables—for example, tables containing security group and user 
information. 


Configurations of the SilverStream server meant for developers provide Sybase Adaptive 
Server Anywhere and IBM Cloudscape, though you can choose any supported DBMS. 


The SilverStream server is capable of communicating with multiple database engines at once. 
For example, you can install your SilverMaster database on Cloudscape and have all of your 
application databases in another database, such as Oracle. 
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Preparing the database to be a SilverMaster 


You need to create a database to use as your SilverMaster before installing the SilverStream 
server (unless you are using Cloudscape or the bundled version of Adaptive Server Anywhere 
as your SilverMaster, in which case the installation program can create a database for you). 


The SilverStream server must connect to a database that is to be used as the SilverMaster and 
any other databases you want to access from the SilverStream server. The SilverStream server 
acts as a database client, so the server requires any database client software, ODBC driver, 
JDBC driver, and any configuration necessary for an application connecting to a particular 
database. 


The steps for setting up a database differ for each database type. See the appropriate chapter in 
this guide for more information about setting up your database type. 


LL) For more information about the SilverMaster database and setting it up, see the 
Administrator’s Guide (especially the chapter on data source configuration). 


Choosing the installation type 


The SilverStream server installation program provides several types of installation that let you 
tailor the environment to your needs. Your choices include the following (not all choices are 
available with all editions): 





Choice Description 





Server Only Install | Installs all the necessary SilverStream software program files for the 
edition you are installing. This installation option is recommended 
for most users. 


For Classic Edition, this option includes all of the classic sample 
applications (if Sybase Adaptive Server Anywhere is found on your 
system). It creates any ODBC settings that are needed by the sample 
databases, but it does not add them to your server. You must add a 
sample database to your server before you can run the application. 


With Enterprise Edition, this option installs the SilverJRunner 
Installers on the server. These Installers allow your end users to 
download SilverJRunner (and SilverJ2EEClient) from a page that is 
running on the server. If you are installing Developer or Classic 
Edition and want to install the SilverJRunner Installers on the server, 
you need to choose Full or Custom Install. 
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Choice Description 





Full Install Installs all the software for your edition. 


For Classic Edition it also adds all of the sample application 
databases to your server (if Sybase Adaptive Server Anywhere is 
found on your system). If you do this type of install, the SilverStream 
server starts all of the database engines for the sample application 
databases as part of the server startup. This option is provided for the 
convenience of users who want to explore all the SilverStream 
classic sample applications. 


For Classic Edition, choose this option (or a custom install) to install 
the EDC client-side components (DSO wizards) and third-party 
integrations (not currently available). 


This option installs the SilverJRunner Installers on the server with all 
editions. 





Designer Only Installs the SilverStream Designer, SilverJRunner, SilverJ2EEClient, 
SilverStream Management Console, deployment tools, and the online 
Help. Does not install the SilverStream server. 


Choose this option only if you will be developing classic applications 
against a SilverStream server located on another computer. 





SilverJRunner Installs SilverJRunner (which allows end users to run classic 
SilverStream Java forms and views) and SilverJ2EEClient 
(SilverStream’s J2EE application client container). 


Note that end users can also download SilverJRunner and 
SilverJ2EEClient from a running SilverStream server (this is true 
with Developer or Classic edition servers only if the server was 
installed using Full or Custom Install). 





SMC/Deploy Installs the SilverStream Management Console, tools needed to 
deploy applications to a SilverStream server, and Core Help files. 
Does not install the SilverStream server. 


Choose this option if you only need to run the SMC or deploy to a 
SilverStream server (for example, if you are using SilverStream 
eXtend Workbench and need to deploy to a SilverStream server). 
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Choice Description 





Cluster Managers Installs the SilverStream Load Balancer, Dispatcher, and Cache 
Manager. This option is for server administrators who want to install 
the load balancing tools on a different computer than the 
SilverStream server. 





Custom Install Allows you to choose exactly which components are installed. 


For Classic Edition, choose this option (or a full install) to install the 
EDC client-side components (DSO wizards) and third-party 











integrations (not currently available). 





About the classic sample applications 


SilverStream Classic Edition provides classic SilverStream sample applications (applications 
using SilverStream pages, forms, and business objects). 


LL) For details on these, see “Sample Applications” in the Getting Started book of the 
server's Classic Development Help. 


Installing the SilverStream server and programs to run as a service or a 


daemon 


When you are running high-availability servers in a multiuser environment, it often makes sense 
to run servers as a Windows service or as a UNIX daemon. Running the SilverStream server and 
the database server as a service or daemon on the same machine ensures that both services will 
restart automatically when the machine reboots. You can set the SilverStream server to run as a 
service or a daemon using the installation program. By default, the SilverStream server runs as 
a desktop program, not as a service or a daemon. 


Running the SilverStream server as a service or a daemon allows you to: 

e Avoid security risks caused by keeping the server program logged in on the computer 
running the server 

e Automatically start the server whenever Windows or UNIX is started 

e Start the server remotely with the Windows Service Manager or with a UNIX shell 

e Pass startup parameters to the server 


e Run the server with administrative account privileges while you run other programs using 
your local accounts 


e Avoid tying the server to a specific user ID 
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SilverStream programs that can run as services or daemons 


The following table lists the SilverStream programs that can also run as services or daemons. 





Program 


Description 


Runs as 





SilverStream server 


Serves applications 


By default, runs as a desktop 
program 

















in sync 





Load Manager Manages the activity of the Usually run as a desktop 
servers in a cluster program 

Dispatcher Redirects requests to Usually run as a desktop 
SilverStream servers program 

Cache Manager Keeps server caches for clusters | Usually run as a desktop 


program 





NOTE By default, Sybase Adaptive Server Anywhere runs as desktop programs, though they 
can also be run as services. For more information, see Chapter 11, “Configuring Sybase 
Adaptive Server Anywhere Databases”. 


Guidelines on setting the SilverStream server to run as a service 


or a daemon 


You can configure the SilverStream server to run as a service or daemon when you initially 
install the server using the installation program. However, it’s often easier to install the 
SilverStream server as a desktop program, then test it before configuring it to run as a service or 
daemon. The following steps are recommended when installing the server as a service or 


daemon. 


> To set up the SilverStream server to run as a service or daemon: 


1. Install the SilverStream server as a program (not a service or a daemon) and create a 
SilverMaster database as described in Chapter 2, “Installing the SilverStream Server on 
Windows” or Chapter 3, “Installing the SilverStream Server on UNIX”. 
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2. After your SilverMaster database has been created or updated, configure your database 
server to start as an automatic service if it is running on the same machine. 


NOTE The SilverStream server service requires the database to be running when the 
server starts. By default, the Sybase Adaptive Server Anywhere database is not 
installed as a service. For more information, see “Step 4: Run Sybase ASA as a 
service” on page 96. 
3. If you haven’t already done so, set up any other services that you want to run with the 
SilverStream server, such as Fulcrum or SNMP. 
4. Verify that the SilverStream server is running properly. For more information, see 
“Testing the install” on page 22 for Windows or “Testing the install” on page 42 for 
UNIX. 


5. Run the SilverStream installation program a second time using one of the following 
procedures: 


e “Installing the SilverStream server as a service” on page 26. 
e “Setting the SilverStream server and cluster components to run as daemons” on 
page 38. 


Because you already installed the server as a program in Step 1, no files are copied when 
you change the server to run as a service. You also will not need to run SilverMasterInit or 
create any properties files. 


6. If you are using NT security in your application, you should change the NT Security 
settings on your machine using the NT User Manager. 
LL) For more information on setting User Rights Policy for SilverStream, see the section 


on NT Security in the Administrator’s Guide. For more information about the operation 
and administration of services, see the Windows documentation. 





8 Installation decisions 





eXtend Application Server Installation Guide 





Migrating to Version 4 


To migrate from Version 3 to Version 4, choose use an existing database for your 
SilverMaster. For more information, see the Windows or UNIX installation chapter in this 
guide. 


LL) For complete information about migrating from a previous version of SilverStream, see 
the migration document in Getting Started of the server’s Classic Development Help. 


Contacting Technical Support 
SilverStream provides extensive online product support at its Web site: www.silverstream.com. 


In the Support section of the SilverStream Web site, you can learn about the Technical Support 
programs and how to contact Technical Support. You can also access FAQs, tips and tricks, 
known customer issues, patches, links to related information, and so on. You can also use this 
area to submit problems, questions, and enhancement requests. 


To access the member area, you must provide a user ID and password, which you receive when 
you register your product. The installation program provides the opportunity to register the 
product after you complete the install. 


If you contact SilverStream Technical Support for assistance, you will be asked to provide the 
information about your environment contained in the following checklist. 








Category Description 
SilverStream server The build number is displayed at server startup and is displayed 
version in the SilverStream Management Console (SMC) 


In Classic Edition, you can obtain the build number by right- 
clicking the microhelp line at the bottom of the Designer 





Product type The server edition you are using 





Operating system The platform for your server 





Database platform for The DBMS you are using for your SilverMaster 
SilverMaster 





Database Type or types of DBMSs you are using with the SilverStream 
server, including versions 
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Category 


Description 





Database driver 


The type and version of the database driver you are using 





Browser 


The version of Internet browser you are using 





Java Virtual Machine 
version (JVM) 


The version of your JVM is displayed when you start the 
SilverStream server 








Proxy servers and 
firewalls 





Whether you are using a proxy server or firewall in your system 
configuration 








In addition, be prepared to provide the following information about the problem you have: 


Does the problem occur in the development environment or at runtime? 


What was the specific action that caused the error? 


What exact error message did you see? 


Can the problem be recreated consistently? 


What are the exact steps to recreate the error? Please be prepared to provide an example. 
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2 Installing the SilverStream Server on Windows 





This chapter describes the SilverStream eXtend Application Server installation program for 
Windows platforms. It contains these topics: 

e System requirements and supported databases 

e Installing the SilverStream server 

e Testing the install 

e — Installing the runtime environment for external Java clients 

e Installing on a non-networked computer 


e — Installing the SilverStream server as a service 


System requirements and supported databases 
See the Release Notes for the latest information on the following: 


e Hardware and software needed to run the SilverStream products 


e Supported databases 


Installing the SilverStream server 


NOTE For updated information about installing SilverStream, see the Release Notes. 


Before you install the SilverStream server, make sure that you have created and configured a 
database to be used as your SilverMaster database (unless you will use IBM Cloudscape or 
Sybase Adaptive Server Anywhere as your SilverMaster; in this case, the installation program 
can create the SilverMaster database). See the appropriate chapter in this guide for information 
on setting up your database type. For general information on database setup for the SilverStream 
server, see the chapter on data source configuration in the Administrator’s Guide. See the 
Release Notes for the database versions and drivers supported for your platform. 


The installation wizard is self-documenting. You can use the documentation provided by the 
wizard to respond to the prompts. This section describes the parts of the installation that might 
require additional information not provided by the wizard. 
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> To install the SilverStream server: 
1. Exit all Windows programs, including Microsoft Outlook, before running the installation 
program. Otherwise, the installation program might not be able to proceed. 


2. Insert the SilverStream server CD into the CD-ROM drive. The installation program 
automatically starts. 


You first have the opportunity to view the Release Notes that are appropriate for your 
edition of the server. The Release Notes contain important information. Please take the 
time to read these notes carefully before continuing. 


Next the installation program displays the SilverStream license agreement. To install the 
SilverStream server, you must accept this agreement. 


3. Choose Yes and continue with the installation. 
4. Choose Install software and select Next to continue. 


You come to a panel similar to the following. 


SilverStream eXtend AppServer 4.0 Eg 


Installing Sybase Adaptive Server Anywhere and a 
Fulcrum Search Server is recommended. 





Fulcrum SearchServer allows you to create 
full-text searchable applications. Sybase 
Adaptive Server Anywhere is a relational 
database. 





I Install Sybase Adaptive Server Anywhere 8.0 (Authenticated) 
Installing Adaptive Server Anywhere is required 
to use the SilverStream classic sample 
applications (applications using SilverStream 
pages. forms, and business objects). To use the 
SilverStream sample J2EE applications, you can 
use either Adaptive Server Anywhere or Informix 
Cloudscape (which is provided with Developer 
Edition). 


Install SilverStream eXtend Application Server. 


After installing Adaptive Server Anywhere or 
Fulcrum Search Server. you must restart your 
computer. 








y cs | 


NOTE You see the choice for Sybase Adaptive Server Anywhere only if you are 
installing Developer or Classic Edition; the authenticated version of Adaptive 
Server Anywhere is available only with these editions. If you want to use 
Adaptive Server Anywhere with a different SilverStream server edition, you need 
to purchase the full DBMS from Sybase. 


5. Choose Install SilverStream eXtend Application Server and optionally Install 
Fulcrum Search Server and Install Sybase Adaptive Server Anywhere 
(Authenticated). 
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e — Install Fulcrum SearchServer if you want to create applications that are full-text 
searchable. 


Fulcrum is installed into the SilverStream installation directory, so you cannot install 
Fulcrum without installing (or having previously installed) the SilverStream server. 


e Install Sybase Adaptive Server Anywhere if you want to use that DBMS as your 
SilverMaster or application database, or if you want to run the classic SilverStream 
sample applications. 


If you choose to install Adaptive Server Anywhere, the ASA installation program will 
launch. You can choose all the defaults. Once that installation is complete, you will 
return to the SilverStream installation program. 


NOTE If you later uninstall ASA, then reinstall it without reinstalling the 
SilverStream server, in order to keep using the authenticated version of ASA 
you need to open the saopts.sql file in the ASA scripts directory and insert 
the following single line after the line -- populate SYSOPTIONS: 

SET OPTION 
PUBLIC.DATABASE AUTHENTICATION='Company=SilverStream;Application=Sil 
verStream; Signature=010fa55157edb8e14d818eb4fe3db41447146f1571g21641 
3009£€84418053690cca7bd8477£20fbf 2a! ; 
6. You come to a panel similar to the following (the choices listed depend on the edition of 
the SilverStream server you are installing). Choose the appropriate installation type and 
choose Next. 


LL) For information about when to choose each of these types, see “Choosing the 
installation type” on page 4. 


SilverStream eXtend AppServer 4.0 x| 


“Server only install’ (recommended for most users) a 
installs all the files required by the SilverStream 
Server. 

























Install all files required to run the 
SilverStream Application server. 
‘Full install" installs all common SilverStream 
software and configures your server to load all C Full Install Install all common SilverStream 
sample applications at startup. = components. 


‘Designer only’ installs the SilverStream Cc ; i i 

Deraan Sive Nane and ihe EVERA or Designer only Install Designer, Help and SilverJRunner. 
Help. The SilverStream Server will not be 

installed. The ‘Designer’ option should be used TERENE Install the Siel Runner and 


only if you will be developing all of your 
applications against a SilverStream Server 
located on another computer. 


SilverJ2EEClient. 


SMC / Deploy Install the SilverStream Management 


‘SilverJRunner' installs SilyerJRunner and Console (SMC) and Deployment tools 
SilverJ2EEClient which allows users to run 3 5 
SilverStream Java forms and J2EE application ™ Custom Install Select which components to install. 


clients. Users can also download SilverJRunner 
from the SilverStream Server. 


‘Custom Install" will allow you to choose exactly zl < Back Cancel | 
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7. Continue through the install until you come to a panel that prompts you to configure the 
SilverStream server. Most users should accept the default settings. 


SilverStream eXtend AppServer 4.0 Eg 


| 
The SilvyerMaster database must be configured ál 
before you can start your server. 





Default values are recommended. Do not 
change these options unless you are an 
experienced user. The server will not start if it is 
not properly configured. 





T Install the SilverStream Server as a Service. 
"Configure SilverStream Server” should be 
checked, especially if you are upgrading your 
existing server. Uncheck it ONLY if you are 
reinstalling the software for your existing server 
and SilverMaster version. I Configure (Broker MQ. 


I Install a new Server configuration file. 


Later in the installation you will choose whether 
to run SilverMasterlnit in FULL mode (Initialize) 
or REFRESH mode (Upgrade). 

Installing the server as a Windows Service 
allows your server to start automatically when 
Windows is started. To select this option, you 
should be familiar with the operation and 








administration of Windows Services. =| < Back Cancel | 











Option Description 

Configure SilverStream In nearly every situation, you should select this option. 
Server (execute Select this option when installing the server the first time 
SilverMasterInit) and also when upgrading from a previous version of the 


server (selecting this option will bring your existing 
SilverMaster up to the current version, which is required). 


The only time you would deselect this option is when you 
reinstalling the same version of the server and already 
have a functioning SilverMaster. 





Install the SilverStream If you select this option, see “Installing the SilverStream 
Server as a Service server as a Service” on page 26 for more information. 
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Option 


Description 





Install a new Server 
configuration file 


You see this option if you are installing this server version 
over an existing version. Select this option if you want to 
create a new httpd.props file; deselect the check box if 
you want to maintain your existing httpd.props file. 





Configure jBroker MQ 








jBroker MQ is the JMS server that accompanies the 
SilverStream server. 


Selecting this option has two effects: 


e The jBroker MQ installation program will be launched 
at the end of the SilverStream server installation, and 
you will be able to configure jBroker MQ (for 
example, you can specify the database to hold the 
persistent data) 


e The JMS server will be started automatically by the 
SilverStream server when it starts 


If you deselect this option, jBroker MQ will be silently 
installed (it is required by the server), but you will not be 
able to configure it at that time and it will not be 
automatically started by the SilverStream server. You will 
need to configure it later in order to use it (for example, 
you will have to initialize its database). 


LL) For details on this jBroker MQ configuration 
choice, see the chapter on running the server in the 
Administrator’s Guide. For information about jBroker 
MQ, including how to initialize its database, see the 
jBroker MQ Help. 
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8. When you encounter the prompt in the following panel, specify the database type of your 
SilverMaster database. 
. < | Which type of database would you like to use for the SilverMaster 
The SilverStream S l 7 
Matted aaa aaa en” E eea 
Press the Launch button to see the database 
aus oe Foel ; IBM DB2 UDB 5.2 
fic installation instruct luded in th 
maha alates ion instructions included in the IBM DB 2UDB G1 Lal 
Note: "Adaptive Server Enterprise" was formerly Reed pd hy a 3.x) 
known as "Sybase SQL Server". Microsoft hoss POME Saver 
Microsoft SQL Server 2000 
Microsoft SQL Server 6 
Microsoft SQL Server 7 
Oracle 7 
Oracle 8 
Oracle 9i 
Sybase Adaptive Server Anywhere 6 E 
Launch database help for: | 
Informix Cloudscape 
i cao | 
If you select Cloudscape or Sybase Adaptive Server Anywhere, you can specify in the 
next panel whether the SilverStream installation wizard will create a new database or use 
an existing database. If you are upgrading from a previous server version, you should 
choose to use your existing database. 
For all other database types, you must use an existing database that you have already 
configured for use as a SilverMaster database. The configuration requirements are 
described in this guide in the database-specific chapters. 
G For more information about configuring each of the database types, click the 
Launch database help for databaseName button for the selected database. The 
corresponding chapter of this guide is opened. 
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9. If you are using an existing SilverMaster, you see the following panel. 


SilverStream eXtend AppServer 4.0 x| 


Choose “Initialize the SilverMaster database" if al 
you are installing a new server for the first time. | 
This option will run a FULL SilverMasterInit. 



















Choose “Upgrade your existing SilverMaster” if 
you are installing a new software version for an 
existing server installation. This option will run 
SilverMasterlnit with the REFRESH option and C Upgrade your existing SilverMaster 
will also upgrade existing SilyerMasters to the 
current software version. 





Users, groups and other security information 
stored in the SilverMaster are not lost during a 
refresh of the SilverMaster database. 


DATABASE UPGRADE IS NOT REVERSIBLE. 
BEFORE UPGRADING, YOU SHOULD MAKE A 
BACKUP OF YOUR SILVERMASTER DATABASE 
AND ALL DATABASES REFERENCED BY IT. 


Please refer to the documentation for more 
information about upgrades. 











zI < Back Cancel | 





e Ifyou choose Initialize the SilverMaster database, the install procedure upgrades the 
database to the current version and also removes any existing database tables, security 
settings, and user information. (It runs SilverMasterInit in its FULL mode.) 


e Ifyou choose Upgrade your existing SilverMaster, the install procedure upgrades 
the database to the current version but retains all of the database tables, security 
settings, and user information. (It runs SilverMasterInit in its REFRESH mode.) 





CAUTION Make sure that you have backed up your existing SilverMaster before 
initializing or upgrading it. 





Choose the appropriate radio button, then choose Next. 
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10. Enter information about your SilverMaster database (unless you are having the installation 


program create a Cloudscape or ASA database as your SilverMaster). 


The following table describes the type of information you will be asked for. 





Database type 


Required information 





Cloudscape 


Name of the SilverMaster database 


The user name and password that the SilverStream 
server will use when connected to the database 


JDBC URL 





DB2 


Alias name of the SilverMaster database 


The user name and password that the SilverStream 
server will use when connected to the database 





Informix 


Name of the SilverMaster database 


The user name and password that the SilverStream 
server will use when connected to the database 


Server host name 
Server name 


JDBC port number 





Microsoft Access 


Database driver version 
ODBC name of the SilverMaster database 


The user name and password that the SilverStream 
server will use when connected to the database 





Microsoft SQL Server 








Database driver type (SQL Server 2000 only) 


ODBC name of the SilverMaster database (if using 
ODBC) 


The user name and password that the SilverStream 
server will use when connected to the database 
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Database type 


Required information 





Oracle 


e Database driver type and whether to use synonym 
support (versions 8 and 9i only) 


e Alias name of the SilverMaster database 


e The user name and password that the SilverStream 
server will use when connected to the database 





Sybase Adaptive Server 
Anywhere 


e Database driver type 
e Name of the SilverMaster database 


e The user name and password that the SilverStream 
server will use when connected to the database 


e If using the jConnect driver: host name and JDBC port 


number 





Sybase Adaptive Server 
Enterprise 


e Database driver type 
e Name of the SilverMaster database 


e The user name and password that the SilverStream 
server will use when connected to the database 


e Host name 


e JDBC port number 





Sybase SQL Anywhere 








¢ ODBC name of the SilverMaster database 


e The user name and password that the SilverStream 
server will use when connected to the database 








NOTE Ifyou see a warning about AGCLASSPATH at this point, it is because you didn’t 


add the database driver you are using to your AGCLASSPATH environment 


variable. For details on defining AGCLASSPATH, see the chapter on your 
DBMS in this guide and the chapter on data source configuration in the 
Administrator's Guide. 


11. Choose the port that the server will listen on. 


LL) For more information, see the chapter on running the server in the Administrator’s 


Guide. 
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12. 


13. 


If you are creating or initializing a SilverMaster database, you see a panel that concerns 
security. 


SilverStream eXtend AppServer 4.0 x] 


The default installation option will restrict access a 
to the SilverStream server when initializing the 
SilverMaster database. When access to 
SilverMaster is restricted, unauthorized users will 
not be able to access administration operations C Restrict access to the SilverStream server 
nor browse directory listings. Access to 
administrative settings and resources will be 
limited to members of the Administrators group. 
Only members of the Administrators and 
Developers groups will be able to browse 
directory listings. All users will be required to log 
in whenever they access the server. When 
server access is restricted, all users will have 
Execute permission which enables them to run 
applications. 























Restrict access to the SilverStream server? 





Installing the SilverStream server with the Do Not 
Restrict Access option means that all users WILL 
be able to perform administrative operations and 
browse directory listings until you lock down 
access by setting permissions. 


Recommendations: zi < Back Cancel | 














Select Restrict access to the SilverStream server if you want to restrict initial access to 
the server as described on the panel (you can always change the security settings later). 


LL) For more information, see the chapter on using security in the Administrator ’s 
Guide. 


If you are creating a new SilverMaster or initializing an existing SilverMaster, you will 
then be asked to define a user name and password for the SilverStream user who will 
administer the server. The installation program will create a user with this name and 
password and assign this user Locksmith privileges. Your server’s administrator will log 
in to the server using this account. 


C For more information, see the chapter on setting up users and groups in the 
Administrator's Guide. 
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14. 


15. 


16. 


17. 


18. 


Continue with the installation following the prompts. After you specify the program folder 
to create, you see the following panel listing your selections. 










SilverStream eXtend AppServer 4.0 x| 





Setup has enough information to start copying the program files. 
E If you want to review or change any settings, click Back. If you 
SilverStream are satisfied with the settings, click Next to begin copying files. 
eXtend 


APPLICATION SERVER 


i 


Current Settings: 
SilverStream installation information: 






Target: 
c:\SilverStream\exXtend4ppServer 





Start Menu Folder: 
SilverStream exXtend\AppServer4.0 


Components selected: 
Designer 
Server\Server files 
Server\NT only files 
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Review your selections. If they are correct, choose Next to begin the installation. 


When the installation nears completion, you receive the message Creating Resources. 
This will take a few minutes. SilverStream builds the SilverMaster. 


Once you are brought into License setup, enter your serial number and register the 
product. 


If you chose to configure jBroker MQ, the jBroker MQ installation program launches. Go 
through the installation. 


(J For more information, see the jBroker MQ Help. 


If you chose Custom Install to install an Enterprise Data Connector, the installation 
program prompts you to install the server components. 


LL) For more information, see Chapter 4, “Installing Enterprise Data Connectors”. 
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Testing the install 


To test your SilverStream server installation, start the SilverStream server and the SilverStream 
Management Console (SMC). 


The SilverStream server and SMC are separate executables. You need to start each separately, 
unless you set up the server to run as a service. 


LL) For complete information about starting and stopping the SilverStream server, see the 
chapter on running the server in the Administrator's Guide. 


To start the SilverStream server and SMC from the Start menu: 


1. From the Start menu choose Programs, then choose the SilverStream eXtend program 
group. 
2. Select AppServerVersion>SilverStream Server. 


The SilverStream server must be running for you to connect the SMC to it. Your local 
machine is the default machine for running the server. It is called localhost. By default, 
the server listens to port 80 on the local machine. 


3. Wait for this message: 
SilverStream Server ... serving at: http://host_name:port ... 


4. Go back to the SilverStream eXtend program group and select SilverStream 
Management Console. 


You see a splash screen, then the SMC. 


NOTE As part of your testing, it is also good idea to verify that any services that the 
SilverStream server depends on are running and set to start automatically when 
the system reboots. 


LL) Ifyou encounter a problem, see the troubleshooting chapter in the Administrator’s Guide. 
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Installing the runtime environment for external Java clients 


If you need to deploy an external Java client to a user machine, you can use the SilverStream 
server installation program to set up the runtime components required on that machine. 


> To set up the runtime environment on a user’s machine: 
1. Start the SilverStream server installation program and specify Custom Install. 
2. Select only JRE with jBroker. 
This installs the required versions of: 
e Java 2 Runtime Environment (JRE) 
e Java HotSpot Performance Engine 
e jBroker 


LL) For more information on deploying external Java clients, see the chapter on writing 
external Java clients in the Programmer's Guide of the server’s Classic Development Help. 


Installing on a non-networked computer 


The SilverStream server is designed for serving applications over the Web. Whether your 
machine is networked or not, the SilverStream server needs access to the TCP/IP protocol to 
function properly. If your machine is networked, verify that TCP is configured to run the 
SilverStream server properly. 


Verifying that TCP/IP is installed on your computer 


This section describes how to verify that TCP/IP is installed on a computer running on Windows 
platforms. 


Windows NT 


> To verify that TCP/IP is installed on Windows NT: 


1. Go to the Control Panel and select the Network icon. 
2. Select the Protocols tab. 
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Select TCP/IP Protocol and click Properties. 


If you do not see TCP/IP installed, you must install it. Check with your LAN administrator 
for the details of TCP/IP in your installation. If TCP/IP is not run at all on your LAN, see 
“Installing a TCP/IP connection under Windows NT” on page 24. 

Once you have TCP/IP installed, from a DOS command prompt type ping localhost. You 
should see the replies from your machine indicating that TCP/IP is functioning properly to 
contact your local machine. 


Windows 95/98 


> To verify that TCP/IP is installed on Windows 95/98: 


1. 
2. 


Go to the Control Panel and select the Network icon. 

Select TCP/IP Protocol and click Properties. 

If you do not see TCP/IP installed, you must install it. Check with your LAN administrator 
for the details of TCP/IP in your installation. If TCP/IP is not run at all on your LAN, see 
“Installing a TCP/IP connection under Windows 95/98” on page 25 and add the MS 
Loopback adapter. 

Type ping localhost from a DOS command prompt and verify that replies come back 
indicating that TCP/IP is installed and able to communicate with your machine 
(localhost). 


Installing a TCP/IP connection under Windows NT 


> To install a TCP/IP connection under Microsoft Windows NT: 


D COE ee N 


Go to the Control Panel and select the Network icon. 

Click the Adapters tab. 

Click Add. 

Select the MS Loopback Adapter and click OK. 

The value 802.3 appears in the Frame Type field. Click OK. 


Install the necessary files from the NT Workstation CD or NT Server CD (depending on 
NT configuration). 


Click the Protocols tab. 
Click Add. 
Select TCP/IP Protocol. 
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10. Install the necessary files from the NT Workstation CD or NT Server CD (depending on 
NT configuration). 


It will install the hosts file and ping.exe along with other support files. 
11. Click the Properties button for the TCP/IP protocol. 
12. Click the DNS tab and enter the Host Name (for example, SilverHost). 
13. Select the IP Address tab. 
14. Select the MS Loopback Adapter from the Adapter dropdown list. 
15. Click on Specify an IP Address. Enter an IP Address (for example, 200.200.200.200). 
16. Specify a Subnet Mask (for example, 255.255.255.0). 
17. Reboot your computer. 


18. Rename or copy the hosts.sam file to hosts, with no file extension. Using Notepad, edit 
the hosts file by adding an entry for the IP Address/Host Name that you defined 
previously (for example: 200.200.200.200 SilverHost). 


19. To test this address, go to a DOS prompt and type: ping SilverHost. You should then see 
responses from the IP address that you defined. This will be the host name that the 
SilverStream server will use. 


Installing a TCP/IP connection under Windows 95/98 


> To install a TCP/IP connection under Microsoft Windows 95/98: 


Go to the Control Panel and select the Network icon. 

Select the Configuration tab. 

Click Add/Protocols. 

Select Microsoft/TCPIP. 

Install the necessary files from the Win95/98 CD. 

It will install the Imhosts.sam file and ping.exe along with other supporting files. 
6. Go back into Properties for TCP/IP. 


7. Select DNS Configuration. You must enable DNS and supply a Host Name (for example, 
SilverHost). You must specify an IP address (for example, 200.200.200.200). You must 
also specify a Subnet Mask (for example, 255.255.255.0). 


8. Reboot your computer. 


Sule Nes 


9. Rename or copy the Imhosts.sam file to hosts, with no file extension. Using Notepad, edit 
the hosts file by adding an entry for the IP Address/Host Name that you defined 
previously (for example, 200.200.200.200 SilverHost). 
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10. To test this address, go to a DOS prompt and type: ping SilverHost. You should then see 
responses from the IP address that you defined. This will be the host name the 
SilverStream server will use. 


Installing the SilverStream server as a service 


When you are running high-availability servers in a multiuser environment, it often makes sense 
to run servers as Windows services. Running both the SilverStream server and the database 
server as services on the same machine ensures that both services will restart automatically 
when the machine reboots. If the databases that the SilverStream server connects to do not 
reside on the same machine as the SilverStream server, you should also set these databases to 
restart automatically on reboot. 


Before you install the SilverStream server as a service, review the recommendations in 
“Guidelines on setting the SilverStream server to run as a service or a daemon” on page 7. The 
following procedure assumes that you have already done the following: 


e Installed the SilverStream server as a program (not as a service) and verified that the 
server starts properly and connects to the SilverMaster 


e Configured your database server to run as a service 


Using the installation program, proceed with the following steps. 


> To set up the SilverStream server to run as a Windows service: 


1. Insert the SilverStream server CD into the CD-ROM drive. The installation program 
automatically starts. For more information, see “Installing the SilverStream server” on 
page 11. 


2. After the Setup Welcome and the license agreement screens, choose Install Software and 
choose Next to continue. 


3. Select Install SilverStream eXtend Application Server and choose Next to continue. 


4. You see a screen similar to the following. Choose Custom Install and choose Next. 
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SilverStream eXtend AppServer 4.0 x| 


“Server only install’ (recommended for most users) a 
installs all the files required by the SilverStream 
Server. 





















Install all files required to run the 
SilverStream Application server. 





‘Full install’ installs all common SilverStream 


software and configures your server to load all C Full Install Install all common SilverStream 

sample applications at startup. x components. 

‘Designer only’ installs the SilverStream Cc ; i i 

Designer! Sivoifiunnar, ami tho filelertan of Designer only Install Designer, Help and SilverJRunner. 
Help. The SilverStream Server will not be 

installed. The ‘Designer’ option should be used C SilverJRunner Install the SilverJRunner and 


only if you will be developing all of your 
applications against a SilverStream Server 
located on another computer. 


SilverJ2EE Client. 


SMC / Deploy Install the SilverStream Management 


‘SilverJRunner' installs SilyerJRunner and Console (SMC) and Deployment tools 


SilverJ2EEClient which allows users to run x E 
SilverStream Java forms and J2EE application C Custom Install Select which components to install. 
clients. Users can also download SilverJRunner 
from the SilverStream Server. 


‘Custom Install" will allow you to choose exactly zl < Back Cancel | 














5. Inthe Components list box shown in the following screen, select the SilverStream Server 
check box and deselect all the others (note that SMC, Deployment, and Common are 
automatically selected when you select the server). 


SilverStream eXtend AppServer 4.0 x | 


Select the components you want to install and deselect the components you do not want to install. 














Components: Details: 
SilverStream Designer 
J) SME 
Deployment 
Common K 
[7] Help OK 
T] Sample Applications OK 
DSO Wizards 0K 
Integration Packages OK 
SilverJ Runner installers 0K 
JRE with JBroker 0K 
Description 





SilverStream Server files 








| Destination Folder 


c:\SilverStream\exXtend&ppS erver Browse... | | 


Space Required: 73195 K ae 
Space Available: 2727557 K Isk Space... | 








Sm 
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6. Choose Next. 


7. When you come to the following screen, choose Install the SilverStream Server as a 
Service and deselect the other options. 


SilverStream eXtend AppServer 4.0 Eg 


The SilvyerMaster database must be configured El 
before you can start your server. 





Default values are recommended. Do not 
change these options unless you are an T Configure SilverStream Server (execute SilverMasterlnit). 
experienced user. The server will not start if it is 
not properly configured. 

IV Install the SilverStream Server as a Service. 
"Configure SilverStream Server” should be 
checked, especially if you are upgrading your 
existing server. Uncheck it ONLY if you are 
reinstalling the software for your existing server 
and SilverMaster version. E 


T Install a new Server configuration file. 





Later in the installation you will choose whether 
to run SilverMasterlnit in FULL mode (Initialize) 
or REFRESH mode (Upgrade). 

Installing the server as a Windows Service 
allows your server to start automatically when 
Windows is started. To select this option, you 
should be familiar with the operation and 











administration of Windows Services. z < Back Cancel | 





8. Choose Next. 


The following step assumes that both the SilverStream server and your database server are 
on the same machine. If your database server runs on a different machine from the 
SilverStream server, make sure you can access it using an outside application before 
configuring it to run with the SilverStream service. 


NOTE Ifyou are using Sybase Adaptive Server Anywhere and running the SilverStream 
server as a service, you must configure the database as a service (since it must 
start before the SilverStream server). By default, these databases are not installed 
as a service and will not appear in the list of Available Services until configured 
(as described in “Step 4: Run Sybase ASA as a service” on page 96). 
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10. 


11. 


12. 


13. 


Choose which database server the SilverStream server will use and then choose Next. 


If the SilverStream server will connect to a database server running on the same machine, 
select the database from the Available Services list. When run as a service, the 
SilverStream server requires that the database also run as a service. 


Choose the database server and any other services that the SilverStream Server will depend on. 
If the SilverStream Server will connect to a database running on this machine, select the 
database from the Available Services list. Your database server won't be listed until you 
configure it as a service. Your database server must be running as a service in order for the 
SilverStream Server to start. Add services by highlighting entries in the Available Services list 
box. To remove a service, highlight it and press Delete. 


Available Services Selected Services 





ClipBook Server 





EventLog 

Messenger <- Delete | 
Net Logon 

Network Associates Alert Manager 


Network Associates McShield 
Network Associates Task, Manage Z| 





< Back Next > | Cancel | 





Follow the remaining steps presented by the installation wizard until the SilverStream 
server installation is completed. Since you have already installed the SilverStream server, 
no files are copied. 


LI For more information on finishing the installation, see “Installing the SilverStream 
server” on page 11. 

When the installation program is complete, open the Services Control Panel. The 
SilverStream server will appear in the list of available services. 

Set the SilverStream server to start automatically when the system reboots. By default, the 
service startup setting is initially set to Manual not Automatic. 


G For more information about the operation and administration of services, see the 
Windows documentation. 
For any Sybase Adaptive Server Anywhere database that is configured to run as a service, 


verify that the ODBC Data Source entries match the service configuration (if you are 
connecting using ODBC). 


Where to go next For information on maintaining the SilverStream service as well as 
setting up additional SilverStream services, see the section on maintaining SilverStream 
processes running as services in the chapter on running the server in the Administrator's Guide. 
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3 Installing the SilverStream Server on UNIX 





This chapter describes how to install the SilverStream eXtend Application Server on UNIX and 
Linux. It contains these topics: 


System requirements and supported databases 
Installing the SilverStream server 

Testing the install 

Accessing the SilverStream server 

Setting environment variables 


Troubleshooting 


System requirements and supported databases 


See the Release Notes for the latest information on the following: 


Hardware and software needed to run the SilverStream products 


Supported databases 


Installing the SilverStream server 


This section describes how to install the SilverStream server. It includes the following sections: 


Before you install 

Mounting the CD-ROM drive (AIX) 

Mounting the CD-ROM drive (HP-UX) 

Mounting the CD-ROM drive (Solaris) 

Running the install 

Setting the SilverStream server and cluster components to run as daemons 


Changing the user account and ports 
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Before you install 


NOTE For any updated information about installing the SilverStream server, see the Release 
Notes. 


Before you install the SilverStream server, make sure you have created and configured a 
database to be used as your SilverMaster database. See the appropriate chapter in this guide for 
information on setting up your database type. For general information on database setup for the 
SilverStream server, see the chapter on data source configuration in the Administrator's Guide. 
See the Release Notes for the database versions and drivers supported for your platform. 


You must have Read or Execute rights for the installation directories; otherwise, you will 
receive an error message. 


On UNIX, the SilverStream server listens on port number 8080 by default. If another process is 
occupying that port, the installation procedure lets you specify a different port. If you want to 
set the port numbers to values lower than 1024 (normally reserved for root on UNIX systems), 
you have to be identified as user root. After installing the SilverStream server, you can change 
the user name and ports used by the server. 


LL) For more information, see “Changing the user account and ports” on page 41. 


HP-UX note Java programs can heavily use threads and sockets. HP-UX’s default setting for 
the max_thread_proc kernel parameter is too low for Java applications. You need to increase its 
value to at least 2048. If you don’t, the VM might silently crash. For more information, go to the 
HP Web site (http://www.hp.com) and search for max_thread_proc. 


Mounting the CD-ROM drive (AIX) 


To install the SilverStream server, you must first mount the CD-ROM drive. 


> To mount the CD-ROM drive: 


1. Create the /cdrom directory to be used as the mount point. For example: 
mkdir /cdrom 
2. Mount the CD-ROM drive to the mount point. 
mount -vcdrfs -r /dev/drive mount-point 
where drive is the CD-ROM drive (typically cd0) as seen in the first columns of the 
Isdev -Cc cdrom command and mount-point is the full path to the directory you created to 
mount the CD-ROM drive. 
A typical statement is: 


mount -vedrfs -r /dev/cdo /cdrom 
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Mounting the CD-ROM drive (HP-UX) 


To install the SilverStream server, you must first mount the CD-ROM drive. 


> To mount the CD-ROM drive: 


1. 


Create the /cdrom directory to be used as the mount point. 
mkdir /cdrom 
Start the pfs_mountd and pfsd daemons if they are not already running. 


nohup /usr/sbin/pfs_ mountd & 
nohup /usr/sbin/pfsd & 


Mount the CD-ROM drive to the mount point. 
/usr/sbin/pfs_ mount -x unix -t rrip /dev/dsk/cl1t2d0 /cdrom 
where c/t2d0 is the CD-ROM device. 


Mounting the CD-ROM drive (Solaris) 


The Solaris Volume Management software automatically mounts the CD-ROM to the /cdrom 
mount point. 


Running the install 


Once the CD-ROM drive is mounted, you can install the SilverStream server. You do not need 
to run the installation program with root privileges; you can install as any user. 


> To install the SilverStream server: 


1. 


Change the directory to the CD-ROM mount port. 
cd /cdrom 

Enter the following at the command prompt: 
./install.sh 


The installation script begins. It checks to see whether you have all required patches 
installed. If so, it continues; if not, it tells you what you need to do. 


Press Enter to see the SilverStream license agreement. 


Specify the directory where you want to install the software or press Enter to accept the 
default. 


If prompted, press Y or Enter to create the directory. 


Choose whether to install the sample applications. 
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7. Specify the DBMS you will use for your SilverMaster. 


The information you need to provide depends on the database type you chose. 





Database type Required information 





Cloudscape e SilverMaster database name 
e Database user name 
e Database user password 


e JDBC URL 





DB2 e Directory containing the DB2 client 
e SilverMaster database name 
e Database user name 


e Database user password 





Informix e SilverMaster database name 
e Database user name 

e Database user password 

e Informix host name 

e Informix server name 

e Informix port number 


e Informix installation directory 





Microsoft SQL e SilverMaster database name 
SEEE 200) e Database user name 

e Database user password 
e SQL Server host name 


e SQL Server port number 


e Driver directory 
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Database type Required information 





Oracle e Database driver type and whether to use Oracle synonym 
support (versions 8 and 9i only) 


e ORACLE_HOME directory 
e Oracle TNS name 

e SilverMaster database name 
e Database user name 

e Database user password 


NOTE You can check the connection to the database from the 
machine you are running the installation on using 
sqlplus. For example: 


sqlplus username/password@databasealias 





Sybase e SilverMaster database name 
e Database user name 

e Database user password 

e Sybase host name 

e Sybase port number 


e Directory containing the jConnect classes or JAR file 














8. You are asked whether you want to upgrade a previous version of the SilverStream 
SilverMaster. 
Select Yes to upgrade your previous SilverMaster to the current version. 

9. If you are not upgrading an existing SilverMaster, you are asked whether the installation 
program should configure the SilverStream server—that is, initialize the SilverMaster 
database. Select Yes. 
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10. 


11. 


12. 


13. 


14. 


If you are initializing the SilverMaster, you are asked whether you want to restrict access 
to the SilverStream server. 


If you accept the default (yes), unauthorized users will not be able to access administration 
operations or browse directory listings. Access to administrative settings and resources 
will be limited to members of the Administrators group. Only members of the 
Administrators and Developers groups will be able to browse directory listings. All users 
will be required to log in whenever they access the server. All users will have Execute 
permission, which enables them to run application operations. 


Installing the SilverStream server without restricting access means that all users will be 
able to perform administrative operations and browse directory listings until you lock 
down access by setting permissions. 

Our recommendation: 


e Ifyou are developing SilverStream applications in a development environment, you 
probably do not want to restrict access to the server 


e Ifyou are administering a production environment where applications are deployed for 
use on the Web, you probably do want to restrict access to the server 


LL) For more information, see the chapter on using security in the Administrator ’s 
Guide. 

If you are initializing the SilverMaster, you are asked to define a user name and password 
for the SilverStream user who will administer the server. The installation program will 
create a user with this name and password and assign this user Locksmith privileges. Your 
server’s administrator will log in to the server using this account. 


C For more information, see the chapter on setting up users and groups in the 
Administrator's Guide. 


You are asked to specify the HTTP port. Enter the port number or press Enter to accept 
the default. 


The SilverStream server defaults to port 8080 on UNIX. You need to specify the port 
number when you connect to the server from the SMC or when you specify URLs on that 
server. From the SMC, you specify the server as hostname:portnumber. For example: 


myserver: 8080 


For application URLs on the server, you need to tell the browser what port number the 
server is using (for example, http://myserver:8080/...). 


You are asked to specify the name service port number. This is the port that the 
SilverStream server starts the RMI name services on. Typically you can accept the default. 


Enter the name service port number or press Enter to accept the default. 


You are asked whether you want to configure jBroker MQ. 
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jBroker MQ is the JMS server that accompanies the SilverStream server. Selecting Yes for 

this option has two effects: 

e The graphical jBroker MQ installation program will be launched at the end of the 
SilverStream server installation, and you will be able to configure jBroker MQ (for 
example, you can specify the database to hold the persistent data) 

e The JMS server will be started automatically by the SilverStream server when it starts 

If you select No for this option, jBroker MQ will be silently installed (it is required by the 

server), but you will not be able to configure it at that time and it will not be automatically 

started by the SilverStream server. You will need to configure it later in order to use it (for 
example, you will have to initialize its database). 

LL) For details on this Broker MQ configuration choice, see the chapter on running the 

server in the Administrator ’s Guide. For information about jBroker MQ, including how to 

initialize its database, see the jBroker MQ Help. 
15. Enter your license string and press Enter. 

The installation program displays a screen that contains information about the changes the 

program will make, information about the SilverMaster and SilverStream server settings, 

and the license string. 
16. Ifthe information is correct, select Yes to start the installation. 

The program creates or edits your httpd.props file and sets environment variables in 

.agprofile. A list of the install directories appears, along with the message that the 

program is creating resources. This portion of the installation program, which runs 

SilverMasterInit, may take some time. 


17. If you chose to configure jBroker MQ, the graphical jBroker MQ installation program 
launches. Go through the installation. 


LL) For more information, see the jBroker MQ help. 


18. When the installation completes, you are asked if you want to start the SilverStream 
server. 

19. If you choose Yes, the SilverStream server starts. 
If you choose No, you can start the SilverStream server manually. See “Testing the 
install” on page 42. 


If you want the server to start automatically when the machine boots, use the sample 
startup scripts that are installed on your system. The text preceding the final installation 
prompt tells you where to find the sample startup scripts. 


LL) For more information about using the startup scripts, see “Setting the SilverStream 
server and cluster components to run as daemons” on page 38. 


20. Unmount the CD-ROM device as needed. 
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Installing and using online help If you did not install the SilverStream server online 
help during your server installation, you can install it later: It is located on the CD in docs.tar; 
install it by cd’ing to your SilverStream server installation directory and executing the 


following: 


tar xvf CDdrive/docs.tar 


To start help, open Start_Core_Help.html, which is in the SilverStream Docs directory. 


Setting the SilverStream server and cluster components to run as 


daemons 


The installation program installs sample startup scripts that your system can run to 
automatically start the SilverStream server or cluster components as daemons at boot time. 


Server and cluster sample startup scripts 


The paths to the server and cluster component startup scripts for each supported UNIX platform 
are listed in the following table. See Step 4 of the following procedure for sample commands 


that install the server component for each platform. 





Server path 


Cluster path 





AIX 


Sinstalldir/etc/rc.silverserver 


Sinstalldir/etc/rc.silvercluster 





HP-UX 


Sinstalldir/sbin/init.d/silverserver 


Sinstalldir/sbin/init.d/silvercluster 





Server link: 


Sinstalldir/sbin/rc3.d/S300silverserve 
T 


Cluster link: 


$installdir/sbin/rc3.d/S300silvercluste 
T 





Solaris 








Sinstalldir/etc/rc3.d/S90silverserver 





Sinstalldir/etc/rc3.d/S9 | silvercluster 








As shown in the preceding table, the HP-UX server and cluster component scripts use link files. 
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Using the server sample startup scripts 


A system administrator with root privileges must copy the sample server and cluster scripts 
from the install directory into your operating system’s boot directory. 


LL) For more information, see “Setting up the SilverStream server to run as a daemon” next 
and “Setting up the SilverStream cluster to run as a daemon” on page 41. 


Setting up the SilverStream server to run as a daemon 


To have the server startup script run the next time your system reboots, a system administrator 
with root privileges must copy the script from the install directory into your operating system’s 
boot directory as shown in Step 4 of the following procedure. 


> To set up the SilverStream server to run as a UNIX daemon: 
1. Before you install the SilverStream server as a daemon, review the recommendations in 
“Guidelines on setting the SilverStream server to run as a service or a daemon” on page 7. 


The following procedure assumes that you have already run the installation program and 
created and configured a database to be used as your SilverMaster database. 


2. Locate the sample startup scripts as listed in the preceding table. 
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Edit the server and cluster components startup scripts if needed. 
Copy the sample script from your install directory into the boot directory for your 
platform. The script will run from that directory the next time the system reboots. 
For example, to copy the sample server script for Solaris from an install directory called 
$SILVERSTREA MROOTFete/rc3.d to a boot directory called /ete/re3.d, you would 
type: 

cp $SILVERSTREAMROOT/etc/rce3.d/S90silverserver /etc/rc3.d 














The following table shows platform-specific sample commands. 





Platform | Command 





AIX Sample server copy command: 


cp SSILVERSTREAMROOT/etc/rce.silverserver /etc/ 





HP-UX Sample server copy and link commands: 





cp SSILVERSTREAMROOT/sbin/init.d/silverserver /sbin/init.d 


in -s /sbin/init.d/silverserver 
/sbin/rc3.d/S300silverserver 
The HP-UX sample scripts use links that are similar to those used by 
HP-UX for their startup script environment. In the second command 
above, /sbin/rc3.d/S300silverserver is a link that points to 
/sbin/init.d/silverserver. 





Solaris Sample server copy command: 


cp SSILVERSTREAMROOT/etc/rc3.d/S90silverserver /etc/rc3.d 














LL) For more information, see the “Server and cluster sample startup scripts” on 
page 38. 

Start the SMC (SilverStream Management Console). 

(J For more information, see the Administrator ’s Guide. 


Use the Configuration/General panel to specify the user under whose account the server 
will be started at boot time. To provide security, set the Username for server property to 
your (or another user’s) user account. By default, this property is set to root. 

You should change privileges from root to a different effective user ID. Once a root 
process changes its ownership to become a non-root process, it can’t recover its former 
access privileges. 
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Setting up the SilverStream cluster to run as a daemon 


You can use the sample scripts to start a cluster component as a daemon. By default, the scripts 
run with root privileges. If you want the cluster to start as a user other than root, see your system 
administrator, who can apply the setuid permission to the cluster component script files. 


LL) Fora list of startup scripts, see the table in “Using the server sample startup scripts” on 
page 39. 


Changing the user account and ports 


After installing the SilverStream server, you can change the user account that the server runs 
under. You can also change the ports used by the server. For example, you might want to use port 
80 (the default port for the SilverStream server on Windows) as the runtime port. That requires 
root access, but maybe you want the server to run under a different user account. You could 
perform the following procedure. 


G For more information about the runtime, design, and administration ports used by the 
SilverStream server, see the section on setting up separate ports in the chapter on running the 
server in the Administrator's Guide. 


> To change the user account and ports: 
Open the SMC (SilverStream Management Console). 


Select Configuration options. 

Select the General panel. 

Set Username for server to the user name for the process. 
Change the port numbers as appropriate. 

Click Update. 


Oe OUT ene ON. 


(J For more information about the SMC, see the Administrator’s Guide. 


Using a port lower than 1024 If you specified a port lower than 1024 (such as 80) but a 
user name other than root, you need to do the following: 
e Log in as root and start SilverServer with the SilverServer shell script. 


The server opens the specified port and switches the process UID to the user name you 
specified. 
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Testing the install 


To test your installation, start the SilverStream server. 


LL) For complete information about starting and stopping the SilverStream server, see the 
chapter on running the server in the Administrator's Guide. 


> To start the SilverStream server: 
1. Access the bin subdirectory (for example, /usr/local/silverstream/bin) in the directory 
where you installed SilverStream. Execute the following script: 
./SilverServer & 
2. Wait for this message: 
SilverStream Server ... serving at: http://host_name:port ... 


You must have Read or Execute rights for the installation directories; otherwise, you will 
receive an error message. 


NOTE Itis also a good idea to verify that any services that the SilverStream server depends on 
are running and set to start automatically when the system reboots. 


LO if you encounter a problem, see “Troubleshooting” on page 44. 


Accessing the SilverStream server 


You can access the SilverStream server running on UNIX from the SilverStream Management 
Console (SMC). 


> To access a UNIX SilverStream server from the SMC: 


1. Click the Choose icon from the toolbar or select File>Choose Server. 
A dialog box appears prompting you to enter the name of the server. 
2. Specify hostname:portnumber and click OK. 


A new server icon appears in the left pane of the SMC. This icon displays the name of the 
server you specified. 
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Setting environment variables 


SilverStream creates the environment file .agprofile in the SilverStream server installation 
directory during installation (since it is a “dot” file, you need to issue the Is -a command to see 
it). The SilverStream server sources this file automatically when starting. 


The .agprofile file sets up a proper environment to launch the SilverStream server. It sets 
environment variables for the following: 


SilverStream root location (SILVERSTREAMROOT) 
Java JRE location (JRE_HOME) 
Database location (depends on your DBMS) 


Native libraries (LD_LIBRARY_PATH on Solaris and Linux, SHLIB_PATH on HP-UX, 
LIBPATH on AIX) 


Fulcrum SearchServer (FULCREATE, FULSEARCH, FULTEMP) 
Path needed by the SilverStream server (PATH) 
The SilverStream server class path (AGCLASSPATH) 


Normally this file is only edited by SilverStream during installation. However, you might want 
to alter this file for the following reasons: 


To update the AGCLASSPATH environment variable to include third-party classes 


To update the AGCLASSPATH environment variable and the native search path 
(LD_LIBRARY_PATH, SHLIB_PATH, or LIBPATH) if you access multiple DBMS types 
(Oracle, Sybase, etc.) from the SilverStream server (by adding application databases or 
connection pools to your SilverMaster) 

You must restart the server after changing AGCLASSPATH and before adding a database 
or connection pool. 

LH For details on changing AGCLASSPATH for database driver support, see the 
chapter on data source configuration in the Administrator's Guide. 
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Troubleshooting 


This section describes known problems and their workarounds. 


Invalid license number 


Error message 


***Warning: License improperly installed: SilverStream Software; 


<licensenumber> 
*x*Warning: No valid Licenses found defaulting to Single User 
License. 
SilverStream Server [Build Number: Number] serving at: http://servername: 
portnumber 
Description 


This message may occur if you run SilverMasterInit outside the installation. 


You must reapply your license to the SilverMaster database. Go to your /cdrom/silverstream 
directory and run the following command: 


./upldlic.sh your license number 


X Windows connection errors 


X Windows error message 


Xlib: connection to "sunny:0.0" refused by server 
Xlib: Client is not authorized to connect to Server 


Description 


Messages like these can occur if you are installing on a remote machine. The following 
command or a suitable variation should be run from a remote machine: 


xhost + 
xhost + machinename_of installation 


If after executing the xhost command, you get the following error: 


/usr/openwin/bin/xhost: must be on local machine to add or remove hosts. 


you must execute the command at the server console and not remotely. 
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X Windows error message 


The following message may be caused by an incorrect DISPLAY variable: 


Java exception occurred java.lang.InternalError: Can't connect 
to X11 window server using '!222.111.99.333:0.0' as the value 
of the DISPLAY variable. 


Description 
Try changing the value of the DISPLAY environment variable to one of the following: 


DISPLAY=:0.0 
export DISPLAY 


or 


DISPLAY=machinename:0.0 
export DISPLAY 


Unable to create server socket 


Error message 


***Fatal Error, aborting com.sssw.srv.http.httpd: An unexpected exception 
occurred com.sssw.srv.daemon.ServerHandlerInitException: Unable to 
create server socket on port 80, details: Permission denied at 
com.sssw.srv.http.httpd.initializeServerSocket (httpd.java:1105) at 
com.sssw.srv.http.httpd.initialize (httpd.java:2344) at 
com.sssw.srv.http.httpd.mainBODY = (httpd.java:2437) at 
com.sssw.srv.http.httpd.main(httpd.java:2446) 


Description 
You tried to start SilverServer on port 80 without root privileges. 


Usually only the root user can start a server on port 80. Try logging on as root and starting 
SilverServer, or follow the procedure in “Changing the user account and ports” on page 41. 





Troubleshooting 45 





3 


Installing the SilverStream Server on UNIX 





Corrupted SilverMaster 


Error message 


SilverStream Server loading properties from: 
/opt/silverstream/Resources/httpd.props 

*** Fatal Error, aborting 

com.sssw.srv.http.httpd: An unexpected exception occurred 
com.sssw.srv.daemon.ServerHandlerInitException: An exception 
occurred while attempting to initialize the connection to 
'SilverMaster': 

Unable to find schema for database SilverMaster in AgInfo 
table. 

at com.sssw.srv.http.httpd.initializeProperties 
(httpd.java:1356) 

at com.sssw.srv.http.httpd.initialize (httpd.java:2287) 

at com.sssw.srv.http.httpd.mainBODY (httpd.java:2437) 

at com.sssw.srv.http.httpd.main(httpd.java:2446) 

Java exception occurred java.lang.RuntimeException: 

An unexpected exception occurred 


Description 


If after running SilverServer you see this error, the SilverMaster database has been corrupted 
and SilverMasterInit should be rerun. 


Problems starting SilverServer 


If you would like to start SilverServer without checking the SilverMaster resources, you can 
start the server using the -nodbcheck startup option: 


./SilverServer -nodbcheck 


Full-text search fails 


Error message 


Unable to save a table with a field that is marked "Full Text Searchable". 
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Description 
Full-text search will fail if the directory in which the SilverStream server resides contains a 
hyphen (-) or a period (.). 


Reinstall the SilverStream server into a directory that does not contain a hyphen or a period. 
(Renaming the installation directory is not sufficient, since environment variables are set during 


the installation.) 
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This chapter describes how to install the Enterprise Data Connectors (EDCs) for Lotus Notes 
and SAP R/3. 


It includes the following sections: 

e About the installation software 

e Installing EDCs for the Classic Edition 

e — Installing EDCs for the Enterprise Edition 


e Configuring the environment for Lotus Notes 


Before you begin You should read the SilverStream Enterprise Data Connectors Release 
Notes before installing the SilverStream software components. 


The EDCs require that you install software from the target data source vendor Lotus Notes or 
SAP. The SAP R/3 software must be installed before you install the SilverStream eXtend 
Application Server, or the SilverStream install will not be successful. 


About the installation software 


EDCs include a SilverStream client component (for the design-time environment) and a 
SilverStream server component (for the design-time and runtime environments). 


What’s on the SilverStream Classic Edition (SCE) CD Both the client and server 
components are on the installation CD that is included with the Classic Edition. You install it 
using the Custom installation procedure described in “Installing EDCs for the Classic Edition” 
on page 50. The Classic Edition provides the software for development and testing only. 


What’s on the SilverStream Enterprise Edition (SEE) CD The Enterprise Edition 
provides the software necessary for deployment only. To deploy an EDC on an Enterprise 
Edition server, you must purchase the EDC separately and install it from the EDC installation 
CD. See “Installing EDCs for the Enterprise Edition” on page 51. 
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Installing EDCs for the Classic Edition 


For development, the installation procedure installs both design-time and runtime software 
components. 


> To install EDCs for development: 


1. 


Insert the SilverStream Classic Edition CD into the CD-ROM drive. The installation 
program automatically starts. 


You first have the opportunity to view the Release Notes for Classic Edition. The Release 
Notes contain important information. Please take the time to read these notes carefully 
before continuing. 


Next the installation program displays the SilverStream license agreement. To install the 
EDCs for development, you must accept this agreement. 


Choose Yes and continue with the installation. 

Choose Install Software and select Next. 

Choose Install SilverStream eXtend Application Server. 
SilverStream prompts you to specify the type of installation. 
Choose the Custom Install and select Next. 


SilverStream prompts you to choose the components to install. Select DSO Wizards. 
SilverStream displays the wizards that are available in the Details list box. 


Select the appropriate wizards from the list box. 
You can optionally select other components in the components list box. 


e To install the EDC client and server components on the current machine, make sure 
that both the SilverStream Designer and SilverStream Server are selected. 

e To install only the EDC client components (the Designer Wizards), deselect 
SilverStream Server and select the SilverStream Designer. You will have to install 
the server components on another machine. 

e To install only the EDC server components, deselect the SilverStream Designer and 
select the SilverStream Server. 

When you have selected the components you want, select Next. 

Continue the installation process through to the end of the installation. 

See the chapter on your database type for information about specific steps in the 

installation procedure. For example, if you are installing SilverStream and using Oracle as 

your SilverMaster database, see Chapter 10, “Configuring Oracle Databases”. 
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. Once you have entered the license information and registered the product, you are asked if 


you want to install the EDC software on the server. 


e Ifyou are installing both the client and the server components on the same machine, 
choose Yes 


e Ifyou are installing only the client components, choose No 
e Ifyou are installing only the server components, choose Yes 


The installation program displays the SilverStream license agreement. To install the 
EDC’s server components, you must accept this agreement. Choose Yes. 

Specify the location where the components should be installed (or accept the default), and 
choose Next. 

The installation procedure starts the SilverStream server and uploads the software. It 
notifies you when the installation is complete. 


You must install the appropriate non-SilverStream software for the EDCs and configure the 
machines as necessary before you can begin using the EDCs. 


Installing EDCs for the Enterprise Edition 


For deployment, the installation procedure installs the runtime software components. 


> To install EDCs for deployment: 


1. 


Insert the SilverStream CD into the CD-ROM drive. The installation program 
automatically starts. 


You first have the opportunity to view the Release Notes. The Release Notes contain 
important information. Please take the time to read these notes carefully before 
continuing. 


Next the installation program displays the SilverStream license agreement. To install the 
EDC server components, you must accept this agreement. 


Choose Yes and continue with the installation. 
Enter the EDC product ID for the components that you want to install and choose Next. 


The installation procedure starts the SilverStream server and uploads the software, then 
shuts the server down. It notifies you when the installation is complete. 


You must install the appropriate non-SilverStream software for the EDCs and configure the 
machines as necessary before you can begin using the EDCs. 
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Configuring the environment for Lotus Notes 


When configuring the workstation where the SilverStream server and Lotus Notes Workstation 
processes run, you must set up a Notes User ID to be used by the SilverStream server. 


SilverStream accesses Notes via a single User ID. This User ID must have access to any of the 
Notes databases that must be available at design-time and runtime. See your Notes administrator 
to create and configure the User ID for the Lotus Notes Workstation. 


If a password is required when the SilverStream server accesses Notes, it will display a login 
dialog on the machine running the SilverStream server, not at the client. For this reason you will 
probably want to set up the Notes client on the SilverStream server machine so that entry of a 
password is not required. 
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5 Configuring Cloudscape Databases 





This chapter describes how to configure your IBM Cloudscape database for use as a 
SilverMaster or application database with the SilverStream eXtend Application Server. It 
includes these sections: 

e Setting up SilverMaster databases 

e Setting up application databases 

e Locating Cloudscape databases 

e Cloudscape users, schema, and SilverStream 

e Managing access to Cloudscape databases 

LL) For the latest information on supported database versions, see the SilverStream eXtend 


Application Server Release Notes. In Windows, you can access the Release Notes from the 
SilverStream eXtend program group or from the server’s Core Help. 


Setting up SilverMaster databases 
To use a Cloudscape database as the SilverMaster database, you need to: 


1. Install the Cloudscape software. 


2. Create a Cloudscape SilverMaster database. 


The sections that follow explain these steps. 


Step 1: Install the Cloudscape software 


The SilverStream Developer Edition installation program installs the Cloudscape software by 
default. The installation program copies three JAR files into the SilverStream lib\Cloudscape 
subdirectory. The JAR files are: 














JAR name Description 

cloudscape.jar Provides the Cloudscape JDBC driver 
cloudutil.jar Provides the Cloudscape tools 

RmiJdbc jar Provides the Cloudscape RmiJdbc driver 
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To use Cloudscape databases with the SilverStream Enterprise Edition, you must: 

1. Install the Cloudscape software yourself (it’s available from the Cloudscape Web site at 
www.cloudscape.com) 

2. Do one of the following: 


e Copy these three Cloudscape JAR files to the SilverStream lib\Cloudscape 
subdirectory: cloudscape.jar, cloudutil.jar, and RmiJdbc.jar 

e Specify the location of those three Cloudscape JAR files in the AGCLASSPATH 
environment variable (for information on editing AGCLASSPATH, see the chapter on 
data source configuration in the Administrator ’s Guide) 


As with any SilverMaster or application database, you must be able to connect to the destination 
Cloudscape database from the machine that hosts the SilverStream eXtend Application Server. 


Step 2: Create a Cloudscape SilverMaster database 


You can create a SilverMaster database using either of the following: 


e The SilverStream installation program 


e Cloudscape tools 


The SilverStream installation program During the SilverStream installation process, 
you can specify that the install create a Cloudscape database for your SilverMaster. You should 
specify the user name APP and the password password when prompted. 


Cloudscape tools You can use Cloudscape’s tools to create the SilverMaster database. If 
the Cloudscape database that you use already contains users (not the APP user), then the 
database must also contain a schema of the same name. 


(J For more information, see “Cloudscape users, schema, and SilverStream” on page 57. 


Setting up application databases 


To set up a Cloudscape database as an application database, perform these tasks: 


1. Create the Cloudscape database. 


2. Add the Cloudscape database or connection pool to the SilverStream server. 


The following sections describe these steps. 
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Step 1: Create a Cloudscape application database 


You can create the Cloudscape database: 


Using the Cloudscape tools 
LL) For more information, see the Cloudscape documentation at www.cloudscape.com. 
When you add the database to the SilverStream server 


In this case, you must specify the JDBC URL for the database. You can create the database 
at the same time that you add it by appending the string ;create=true to the URL. 


You can add a Cloudscape database using: 
e The Add Database dialog from the SMC 
e The AddDatabase command of the SilverCmd command-line tool 


LL) For more information on Cloudscape JDBC URLs, see “Locating Cloudscape 
databases” on page 56. 


Using the Add Database dialog Provide these values: 


Database Name 
User name: APP 
Password: password 


By default, Cloudscape databases are created with no security. Use the APP/password 
combination whenever connecting to an unsecured database. 


Database platform: IBM Cloudscape 
JDBC URL: jdbe:cloudscape:databasepath/databasename;create=true 
For example: 


jdbc:cloudscape:c:/mydb/Testdb; create=true 


Using SilverCmd AddDatabase You can invoke SilverCmd AddDatabase like this: 


SilverCmd AddDatabase server[:port] -f file [options] 


The following XML shows the contents of a file that you might specify using the -f parameter. 
This example creates and adds a database named EstoreDB and connects as the user APP. 


<DatabaseOptions isObject="true"> 
<MainDatabase isObject="true"> 
<ConnectionOptions isObject="true"> 
<DatabaseName type="String">EStoreDB</DatabaseName> 
<Username type="String">APP</Username> 
<Password type="String">password</Password> 
<LDSKey type="String">CloudscapeEmbeddedDriver</LDSKey> 
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<OtherDriver isObject="true"> 
<JDBC_URLtype="String">jdbc:cloudscape:c:/mydb/Testdb; create=true 
</JDBC_URL> 
</OtherDriver> 
</ConnectionOptions> 
</MainDatabase> 
</DatabaseOptions> 


Step 2: Add the Cloudscape database or connection pool to the 
SilverStream server 
To add a Cloudscape database to the SilverStream server, follow the steps described in “Step 1: 


Create a Cloudscape application database” on page 55. You do not need the string ;create=true 
when you are adding an existing database. If the database already exists, the string is ignored. 


Another way to access a Cloudscape database is to add a connection pool for it to the 
SilverStream server. For details on adding databases and connection pools, see the chapter on 
data source configuration in the Administrator's Guide. 


Locating Cloudscape databases 
Cloudscape JDBC URLs take this form: 
jdbc:cloudscape: dbname 


The dbname parameter can be a fully qualified pathname, a relative pathname, or a database 
name. The SilverStream server uses the cloudscape.system.home system property to locate 
databases (unless they are fully qualified). By default, the SilverStream server sets the system 
property cloudscape.system.home to the following directory: 


SilverStreamInstallDir\db 


If the SilverStream server is unable to locate the database using the system property, then 
SilverStream tries the current directory. 
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Cloudscape users, schema, and SilverStream 


If the SilverStream server connects to the Cloudscape database as a specific user (not APP), then 
SilverStream requires that the database contain a schema of the same name. For example, if you 
want to connect to a database as the user DBADMIN, then the database must contain a schema 
also called DBADMIN. 


LL) For more information on creating users and schemas, see the Cloudscape documentation 
at the Cloudscape Web site www.cloudscape.com. 


Managing access to Cloudscape databases 


The version of the Cloudscape database that ships with the SilverStream eXtend Application 
Server is designed to support a single database connection. If the SilverStream lib\Cloudscape 
directory exists, or the Cloudscape jars are found on your AGCLASSPATH, the Cloudscape 
database will automatically start in-process with the SilverStream server using the single 
allowed connection. 


Making sure the Cloudscape database does not start automatically If you do not 
want it to start, you can remove or rename the Cloudscape directory without harm. 


Running Cloudscape in a cluster server environment Cloudscape databases are not 
shareable between more than one process at a time and are not appropriate for a cluster server 
environment. 


Connecting to Cloudscape from non-SilverStream tools When the SilverStream 
server has a database open, you must use a different JDBC driver and URL to connect to that 
database from a different source like a JDBC program or a Cloudscape tool. For example, you 
might want to run a JDBC program against that database. 


To use Cloudscape’s ij, you would normally do the following: 


java COM.cloudscape.tools.ij 
ij> connect 'jdbc:cloudscape:d:/MyDbs/MyDatabase'!; 


But to connect while the SilverStream server is running, you would have to run it like this: 


java -Dij.driver=COM.cloudscape.core.RmiJdbcDriver COM.cloudscape.tools.ij 
ij> connect 'jdbc:cloudscape:rmi:d:/MyDbs/MyDatabase'!; 


In CloudView, before connecting to the database click on the Connection tab, and change the 
prefix field to jdbc:cloudscape:rmi://localhost: 1099/. This automatically changes the driver to 
COM. cloudscape.core.RmiJdbcDriver. 
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Allowing access to Cloudscape from external applications When the 
SilverStream eXtend Application Server has a connection to a Cloudscape database, other 
applications are only able to access the database through Cloudscape’s remote RMI/JDBC 
bridge accessed via SilverStream’s RMI/JDBC Listener. The SilverStream eXtend Application 
Server provides the following property, in the httpds.props file, to control the startup of the 
RMI/JDBC Listener: 


http-server.com.sssw.db.cloudscape.cloudscapeDatabaseRMIJDBCListener= 
[true| false] 


The following table describes the property settings: 





Property Value Description 





true Setting this value to true causes the SilverStream eXtend Application 
Server to start the Cloudscape RMI/JDBC listener at server startup. 


Starting this listener makes it possible for other applications (such as 
SilverStream eXtend Workbench’s EJB Wizard) to connect to the 
Cloudscape databases that the SilverStream eXtend Application 
Server is also connecting to (or holding connections to) using 
Cloudscape’s remote RMI/JDBC bridge driver. 





false (default) Setting this value to false prevents the SilverStream eXtend 
Application Server from starting the Cloudscape RMI/JDBC listener 
at server startup. External applications, such as Workbench, will not 
be able to connect to any Cloudscape database to which the 
application server is connected. 


If you do not need external access to Cloudscape then leave this flag 
set to false. When the Cloudscape RMI/JDBC listener is enabled, the 
SilverStream eXtend Application Server is slower to shut down 
because it must do additional processing. When set to false, this flag 
prevents the slower than normal server shutdown. 














Running multiple SilverStream servers ona single host If you want to run 
multiple SilverStream servers on one computer and run Cloudscape, you need to specify a 
different Cloudscape RMI/JDBC port number for each server in its httpd.props file (the default 
is port 1099): 


http-server.com.sssw.srv.cloudscape.RmiJdbcPort=number 


Setting this line to a different port for each server avoids a port number conflict. For more 
information on setting other ports and properties for running multiple servers on a single host, 
see the Administrator’s Guide. 
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This chapter describes how to configure your DB2 databases for use with the SilverStream 
eXtend Application Server as a SilverMaster or an application database. 


(AA) 


For the latest information on supported database versions, see the Release Notes. In 


Windows, you can access the Release Notes from the SilverStream eXtend program group or 
from the server’s Core Help. 


This chapter contains the following sections: 


Supported software versions 
Connecting to DB2 databases 


Troubleshooting 


Supported software versions 


This section details the connection and preinstallation setup recommendations by SilverStream 
Technical Support. Support of DB2 includes the following components: 


DB2 database software The SilverStream server supports DB2 Universal Database 
Version 5.2, Version 6.1, and Version 7.1. The DB2 database can reside on any platform 
that supports connection from the DB2 clients listed below; these platforms include but 
are not limited to AS/400, OS/390, NT, UNIX, and OS/2. 


The database must be a version that supports TCP/IP. In general, the database must be a 
minimum of V4R2 to support TCP/IP. SilverStream has tested with V4R3, although 
version requirements may differ for DB2 depending on the platform. If your DB2 version 
is lower than V4R2, it may require extensive configuration to support Universal Database 
Client. AS/400 and OS/390 environments tend to require more configuration than NT, 
OS/2, or UNIX environments. 

DB2 client software The SilverStream server supports IBM Universal Database Client 
Version 5.2 and DB2 Connect Enterprise Edition versions 6.1 and 7. Users of DB2 5.0 can 
upgrade to Version 5.2 by applying FixPack FP6 9074. Users of DB2 7.1 can upgrade to 
7.2 by applying FixPack 3. 


If you are running software that does not meet the version requirements shown, you need to 
obtain the specified versions. 
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Connecting to DB2 databases 


The SilverStream server connects to DB2 using a Type 2 JDBC driver written by IBM and 
included with their Universal Database client. This driver interfaces with the UDB client to 
establish database connectivity to the back-end DB2 server. SilverStream officially supports 
TCP/IP connectivity, but customers have successfully connected using APPC, IBM’s native 
protocol. 


Follow the steps outlined below to make a DB2 database available to the SilverStream server: 
Step 1: Gather information about your DB2 environment 

Step 2: Prepare DB2 for connection from Universal Database Client 

Step 3: Install the database client 

Step 4: Configure the DB2 client connection 

Step 5: Modify the DB2CLIINI file 

Step 6: Set environment variables 

Step 7: Use the database with the SilverStream server 


DB2 can be used as the SilverMaster database and to store the SilverStream system tables 
required for application databases, with this exception: DB2 cannot be used as a SilverMaster 
(or store SilverStream system tables) when DB2 is running on AS/400 or System 390. 


Note that the application database cannot exist in the same physical space as the SilverMaster 
database, because several of the required tables have identical names. 


Step 1: Gather information about your DB2 environment 


Gather the following information for your DB2 environment. 


e Operating system (for example: OS/390, MVS) 
e Operating system version 

e DB2 version (if different from OS) 

e — Is your database set up for TCP/IP support? 

e Server host name 

e Database name 

e TCP/IP port for the database 

e Service name 


e User ID/password with full read access 
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e Owner, schema, or library list that contains the desired tables and views 


NOTE If your DB2 version is lower than V4R2, your database may require extensive 
configuration to support Universal Database Client. 


Step 2: Prepare DB2 for connection from Universal Database Client 


IBM has extensive documentation available on configuring the database and the client software 
to support connectivity from the Universal Database Client. You can find documentation in the 
Information Center that is installed with the Universal Database Client, or on IBM’s Web site. 


If you have an extremely large database schema, check for additional database configurations 
that can help reduce the time it takes to scan the schema in the DB2CLI._INI file. In addition, see 
the following IBM documents: 

e Preparing MVS/ESA or OS/390 for DB2 Connect 

e Preparing DB2 for AS/400 for DB2 Connect 

e Connecting DB2 for MVS/ESA in a DRDA Network 

e Connecting DB2 for OS/390 in a DRDA Network 

e Connecting DB2 for AS/400 in a DRDA Network Using SNA 

e Connecting DB2 for AS/400 in a DRDA Network Using TCP/IP 


Step 3: Install the database client 


The database client must be installed on the machine where the SilverStream server will reside. 


Using Universal Database Client Version 5.2 (Enterprise Edition) 


Windows NT Follow the instructions in the setup program. Do not confuse the Universal 
Database Client with the Client Application Enablers (CAE). Installing the CAE) will not give 
you all the components you need. You must install the entire Enterprise Connect product. 


Solaris Before you can begin the installation of the DB2 database client on Solaris, you must 
first alter several kernel configuration parameters to accommodate the install. In the /etc/system 
directory: 


set msgsys:msginfo_msgmax=65535 
set msgsys:msginfo_msgmnb=65536 
set msgsys:msginfo_msgseg=8192 
set msgsys:msginfo_msgssz=16 
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Install the database client from the CD. You must install and create a DB2 instance during this 
installation so you can reference the DB2 profile script for SilverStream to successfully use the 
DB2 JDBC driver. 


Using DB2 Connect Version 6.1 (Enterprise Edition) 


Windows NT Follow these instructions for running the setup program: 
1. Choose the DB2 Enterprise - Extended Edition check box. 


You can leave the default choice for the information about the server instance. 
2. Select Custom. 
3. Select the following items from the list: 

e Java Enablement 

e DB2 Connect Server Support 


e Client Configuration Assistant 
UNIX Follow the same instructions as shown above for installing Version 5.2 in Solaris, 
except that you install DB2 Connect - Enterprise Edition Version 6.1. 


HP-UX note: The following are recommended values for HP-UX kernel configuration 
parameters when installing DB2 6.1: 


e  msgseg: 8192 
e  msgmnb: 65535 
e  msgmax: 65535 


e  msgssz: 16 

Using DB2 Connect Version 7 (Enterprise Edition) 

Windows NT Follow the instructions in the setup program. 

HP-UX and Solaris See the JBM DB2 Connect Enterprise Edition for UNIX Quick 


Beginnings guide on the IBM Web site for information on installing DB2 Connect and for 
setting HP-UX and Solaris kernel parameters. 
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Step 4: Configure the DB2 client connection 


Windows NT The SilverStream server connects using DB2 client aliases. These aliases are 
configured using IBM’s Client Configuration Assistant, which can be found in the DB2 for 
Windows NT program folder. In order to run the Client Configuration Assistant, your NT login 
must have administrator authority and the ID must be no longer than eight characters. You need 
to be the DB2 administrator or have administrator privileges to complete these steps. 


> To create a new DB2 client alias: 


NOTE You may have to contact your DB2 Administration staff to obtain some of the 
information required in these steps. 


1. Open the DB2 Client Configuration Assistant from the DB2 for Windows NT program 
folder. 


2. Click the Add button at the top right of the Client Configuration Assistant screen. Select 
Next to continue. 


Choose to manually configure a connection to a DB2 database. Select Next to continue. 
Choose the appropriate protocol (default is TCP/IP). Select Next to continue. 
Choose the appropriate platform or LAN-based. 


ONO Ree 


Configure the DB2 server host name, TCP port number, and service name (optional) that 
your DB2 server is operating on. Select Next to continue. 


7. Enter the target database name. Select Next to continue. 


8. Enter the alias name (you will use this name later to add the database to the SilverStream 
server). Select Next to continue. 


9. (Optional) Register these settings as an ODBC data source. This step is not required but is 
recommended. 


10. Finally, test the connection from inside the Client Configuration Assistant. 


(J For information on installation, see Most Common DB2 Connect Problems on the IBM 
Web site. 
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Solaris In order to establish a connection to your DB2 database, enter the DB2 command- 
line processor and enter the following two commands. 


catalog tcpip node tcpipnodealias remote servername server port# 


where tcpipnodealias is the local alias for your DB2 server (usually the same as the 
servername), servername is the name of the DB2 server, and port# is the port on the database 
server that is set to receive TCP/IP calls. 


catalog database databasename as aliasname at node tcpipnodealias 


where databasename is the actual database name, aliasname is the local name of the database 
(which may be the same as the actual name), and tcpipnodealias is the name given in the first 
catalog statement. 


To test the DB2 connection: 


connect to aliasname user userid using password 


(J For information on installation, see Most Common DB2 Connect Problems on the IBM 
Web site. 


Step 5: Modify the DB2CLI.INI file 


IBM provides a client side .ini file for the purpose of tailoring the client connection to the 
database. Without modifications, the SilverStream server will attempt to add all DB2 tables and 
views into the SilverStream environment. Most applications need only a subset of the entire list. 
Addition of a DB2 database without modifications to the.ini file can take an extraordinarily long 
time. There are several things that can be done to reduce the time it takes for the SilverStream 
server to read the schema. 


One option is to specify the subset of tables to make available to the SilverStream server when 
adding the database to the server. For more information, see the chapter on SilverCmd in the 
Facilities Guide of the server’s Core Help or the section on adding a database in the chapter on 
data source configuration in the Administrator’s Guide of the server’s Core Help. 


Alternatively, you can follow these steps to make changes to .ini file parameters from the Client 
Configuration Assistant: 

1. View the properties for an alias and then choose to modify the ODBC settings. 

2. Connect to the database, then choose advanced. 


The specific settings found to help with SilverStream server installs are listed below. The 
full list can be reviewed in the Call Level Interface document from IBM. 
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Optionally, the DB2 client .ini file can be found in the sqllib directory, and can be read and 
altered using a text editor. Your initial alias entry (with the name you entered via the Client 
Configuration Assistant) should look like this: 


[db2alias] 
DBALIAS=db2alias 


To limit the number of tables that SilverStream shows in the Designer, you can specify a 
particular schema. Schema here refers to the owner/user of the objects or library in the case of 
AS/400. 


SCHEMALIST="userid", "userid2" 


For extremely large datasets, use of SCHEMALIST may not be enough to reduce scanning time. 
To greatly reduce the total number of tables that SilverStream interrogates, you need to 
complete these steps: 


1. Create views of all the system tables using an alternate owner (must be performed by 
DBA). Do not create these views under the same owner ID as the tables you wish to access 
for your application; create them under a unique owner. 

2. Reference that owner of those views in the .ini file. 

SYSSCHEMA="owner" 


For example, you may create your views to see the objects of three different owners. This 
sample view syntax was used for DB2 on NT. 


CREATE VIEW MYSCHEMA.SYSTABLES AS SELECT * FROM SYSIBM.SYSTABLES WHERE 
CREATOR IN ('USER1', 'USER2', 'USER3') 





After views were created for all of the required system tables under the same schema, the entry 
in the ini file would look like this: 


SYSSCHEMA="MYSCHEMA" 


The SilverStream server will then scan only those objects. If used in conjunction with 
SCHEMALIST, the server will scan the objects of the three owners but only add those 
belonging to the owners referenced in SCHEMALIST. 


Important The preceding options are highly recommended to reduce installation and server 
start times. 
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Other configuration options 


For MVS environments, you may have to set a variable for long data type compatibility. For a 
complete description of this setting, see the LONGDATACOMPYT section of the Call Level 
Interface document. 


LONGDATACOMPAT=1 


If you can’t save records in DB2 after adding the database, you may have to set a transaction 
variable. The example listed below is for an AS/400 system and eliminates the need for table 
journaling. For a complete list of options, see the TXNISOLATION section of the Call Level 
Interface document. 


TXNISOLATION=32 


Step 6: Set environment variables 


Windows NT Connecting the SilverStream server to DB2 requires that you add the DB2 
libraries to your AGCLASSPATH environment variable. To do this, open Control Panel / 
System and select the Environment tab. Create a System environment variable called 
AGCLASSPATH and set its value to C:\sqllib\java\db2java.zip (assuming that you installed 
your DB2 client onto the C: drive in the default location); if you did not install the DB2 client 
onto the C: drive, set the AGCLASSPATH variable accordingly. 


By default, this sets up the JDBC 1.0 driver. In DB2 7.x, you can use the JDBC 2.0 driver by 
running this script: sqllib\java12\usejdbc2 (for details, click here). 


UNIX DB2 requires that you add the DB2 JDBC driver’s native libraries and Java classes to 
your Java classpath and system library path. To do this, you may reference the DB2 instance 
(created previously) directly in the SilverStream environment file .agprofile (which is stored in 
the SilverStream server installation directory). Edit .agprofile by adding the following line: 


. /export/home/db2inst1/sqllib/db2profile 


By default, this sets up the JDBC 1.0 driver. In DB2 7.x, you can use the JDBC 2.0 driver by 
adding the following lines to your .agprofile file (for details, click here): 

. /home/db2inst1/sqllib/db2profile 

. /home/db2inst1/sqllib/javal2/usejdbc2 


LL) For more information on editing AGCLASSPATH and .agprofile, see the chapter on data 
source configuration in the Administrator’s Guide. 
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Step 7: Use the database with the SilverStream server 


Now you’re ready to access the DB2 database from the SilverStream server. This enables you to 
do any of the following, as appropriate: 


e Install the SilverStream server and point to that database as the SilverMaster (as 
described in Chapter 2, “Installing the SilverStream Server on Windows” and Chapter 3, 
“Installing the SilverStream Server on UNIX”) 

e Add that database to the SilverStream server for use as an application database 


e Add a connection pool to the SilverStream server for accessing that database 


LI For more information, see the chapter on data source configuration in the Administrator’s 
Guide. 


SilverStream Designer notes The SilverStream Designer (Classic Edition only) will list 
DB2 tables and views. DB2 alias objects cannot be seen from the Designer. SilverStream data 
source business objects can be written to access these objects. 


The SilverStream Designer does not support creating tables or foreign keys for DB2 on MVS. 
Tables and foreign keys must be created outside SilverStream and then synchronized with the 
SilverStream server. 


Troubleshooting 


SQLO0551N “user does not have the privilege to perform operation GRANT” If 
you receive this message from the DB2 client while connecting to DB2 6.1, you may have to 
bind the DB2 utility programs to the database. You must apply the procedure to each database 
you are using with the SilverStream server. Here is the binding procedure: 


1. Log in as your DB2 instance user, such as db2inst1, change to the bnd subdirectory of the 
instance, and start the DB2 utility. 


db2instl@mymachine> cd sqllib/bnd 
db2instl@mymachine> db2 


2. Connect to your database as the DB2 administrator: 
db2 => connect to mydatabase user db2admin using db2admin 
You will see the following info: 


Database Connection Information 
Database server = DB2/NT 6.1.0 
SQL authorization ID = DB2ADMIN 
Local database alias = MYDATABASE 
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3. Run the first bind command: 

db2 => bind @db2ubind.1lst blocking all grant public 
4. Run the second bind command: 

db2 => bind @db2cli.lst blocking all grant public 
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This chapter describes how to configure your IBM Informix database for use with the 
SilverStream eXtend Application Server as either a SilverMaster or application database. 


LL) For the latest information on supported database versions, see the Release Notes. In 
Windows, you can access the Release Notes from the SilverStream eXtend program group or 
from the server’s Core Help. 


This chapter includes these sections: 


e Connecting to Informix databases 


e Troubleshooting 


Connecting to Informix databases 


The SilverStream server is able to access Informix databases through the Informix Type 4 JDBC 
driver (see the Release Notes for the supported version). See the Informix Web site 
(www.informix.com) for details. 


Follow the steps listed below to make an Informix database available to the SilverStream server: 
Step 1: Install the JDBC driver 

Step 2: Create the Informix database and dbspaces 

Step 3: Create the Informix user account 

Step 4: Add the driver path to AGCLASSPATH 

Step 5: Use the database with the SilverStream server 


The sections that follow explain these steps. 
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Step 1: Install the JDBC driver 


You must be able to connect to the destination Informix server from the workstation that will 
host the SilverStream server, so first install the Informix JDBC driver on that machine. 


Step 2: Create the Informix database and dbspaces 


Before you can install the SilverStream server, you must create the actual Informix database and 
the underlying dbspaces. You will need to connect to Informix as a user who is a member of the 
Informix-Admin group. You can create these objects using either Informix Enterprise 
Command Center (IECC) or a command-line utility such as DBACCESS. 


NOTE When creating an Informix database for use with the SilverStream server, make sure 
you turn logging on for that database. 


Step 3: Create the Informix user account 


You need to create an Informix user account that can be used to connect to the SilverStream 
server. This user account must be a member of the Informix-Admin group. See your Informix 
documentation for more information. The password for this account cannot be null. 


Step 4: Add the driver path to AGCLASSPATH 


The location of the Informix JDBC driver (for example, c:\informixdriver\lib\ifxjdbc.jar) must 
be specified in the AGCLASSPATH variable. For Windows, AGCLASSPATH is a system 
environment variable. For UNIX, you'll find it in the .agprofile file. 


LL) For details, see the chapter on data source configuration in the Administrator’s Guide. 
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Step 5: Use the database with the SilverStream server 


Now you’ re ready to access the Informix database from the SilverStream server. This enables 
you to do any of the following, as appropriate: 


e Install the SilverStream server and point to that database as the SilverMaster (as 
described in Chapter 2, “Installing the SilverStream Server on Windows” and Chapter 3, 
“Installing the SilverStream Server on UNIX”) 


e Add that database to the SilverStream server for use as an application database 
e Add a connection pool to the SilverStream server for accessing that database 


LH For more information, see the chapter on data source configuration in the Administrator’s 
Guide. 


Troubleshooting 


This section may help you if you run into trouble using Informix and the SilverStream server. 


Determining driver version To determine which version of the Informix JDBC driver you 
are using, type the following at the command line: 


java -cp pathToDriver\lib\ifxjdbc.jar com.informix.jdbc.Version 


Logical log full You encounter the Informix Server error event Logical Log Full. The 
SilverStream server may not allow you to save data or may not start properly when this problem 
occurs. (You can view this event in the Informix IECC utility’s event list.) 


To resolve this problem, back up the logical log or enable Informix’s Continuous Log backup. 


LL) For more information about resolving this log file problem, see the Informix Enterprise 
Command Center User Guide (IECC) and the Informix Administrator’s Guide. 


Memory capacity You encounter the Informix Server error event Memory Capacity during 
SilverMasterInit or while the SilverStream server is running. (You can view this event in the 
Informix IECC utility’s event list.) 


To resolve this problem, increase the BUFFERS parameter in the ONCONFIG file in the 
Informix /etc directory. See the ONCONFIG environment variable to find this location. 


LI For more information about the ONCONFIG file and the BUFFERS parameter, see the 
Administrator's Guide for Informix Dynamic Server. 
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Setting 


Configuring Microsoft Access Databases 





This chapter describes how to configure your Microsoft Access database for use as a 
SilverMaster or application database with the SilverStream eXtend Application Server. 


LL) For the latest information on supported database versions, see the Release Notes. In 
Windows, you can access the Release Notes from the SilverStream eXtend program group or 
from the server’s Core Help. 


up Microsoft Access databases 


The SilverStream server connects to Microsoft Access using the Microsoft Access ODBC 
driver. This driver is installed with Microsoft Access or Microsoft Office software. 


(J For more information about the driver, see the Microsoft Web site. 


To configure a Microsoft Access database for use with the SilverStream 
server: 


1. Install the Microsoft Access driver onto the machine where the SilverStream server 
resides. 


2. Create the Microsoft Access database. 
3. Install the SilverStream server. 


LL) For information, see Chapter 2, “Installing the SilverStream Server on Windows”. 


The sections that follow explain these steps. 


Step 1: Install the Microsoft Access ODBC driver 


You must have the Microsoft Access ODBC driver software installed on the machine where the 
SilverStream server will be. You must be able to connect to the destination Microsoft Access 
from the workstation that hosts the SilverStream server. 
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Step 2: Create a Microsoft Access database 


Before you can install the SilverStream server, you must create the Microsoft Access database. 


> To create the Microsoft Access database: 


1. Install the Microsoft Access driver on the machine where the SilverStream server will be. 
2. Create the Microsoft Access database using the Microsoft Access GUI tools: 

1. Start Access. 

2. Create the new database using the blank database template. 
3. Create the ODBC data source for the newly created database. 


Your Microsoft Access database is now ready to be used as a SilverMaster or as a SilverStream 
application database. 
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This chapter describes how to use Microsoft SQL Server databases with the SilverStream 
eXtend Application Server. It includes information about using Microsoft SQL Server as a 
SilverMaster database or as an application database. 


LL) For the latest information on supported database versions, see the Release Notes. In 
Windows, you can access the Release Notes from the SilverStream eXtend program group or 
from the server’s Core Help. 


This chapter includes these sections: 


e Basic setup for Microsoft SQL Server databases 
e Setting up JDBC access 
e Setting up ODBC access 


e Using the database with the SilverStream server 


Basic setup for Microsoft SQL Server databases 


You'll perform the following setup steps whether your SilverStream server will access a 
Microsoft SQL Server database via JOBC or ODBC: 


1. Create the database and configure SQL Server. 


2. Create a database login to be used by the SilverStream server. 


Create the database and configure SQL Server 


Before you can install SilverStream, you must first create the actual SQL Server database (and 
underlying database devices). You can create these objects using either ISQL or a graphical tool 
such as SQL Enterprise Manager. 


This section describes how to use SQL Enterprise Manager to create the objects. You need to 
connect to SQL Server using SA or an account with SA privileges in order to create these 
objects. 


> To create a Version 6.5 database: 


1. From SQL Enterprise Manager, connect to the destination SQL Server. 


2. Right-click the database devices folder and select New Device. 
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Ob ee 


Create a Database Device called SilverMasterData and specify a size of 30 MB. 
Create another 30 MB device called SilverMasterLog. 
Right-click the Databases folder and select New Database. 


Create a database called SilverMaster using the devices you created (SilverMasterData 
for the data and SilverMasterLog for the transaction log). 


If you are not going to back up this database regularly, enable the Truncate Log on 
Checkpoint option: right-click the database and select Edit. This option is found on the 
Options tab. 


For SQL Server 6.5, you must verify the size of the TEMPDB database by right-clicking 
on the TEMPDB database and selecting Edit. 


The size of the database is shown on the Database tab. If the size of your TEMPDB 
database is less than 50 MB, extend it by increasing the size of your MASTER device and 
choosing Expand the database (this option is found on the same tab as the Data Size 
value). 

You must verify that you have an appropriate amount of memory allocated to SQL Server. 

This can be done through SQL Enterprise Manager: 

e From SQL Enterprise Manager, right-click the server name and select Configure. 

e From the Configuration tab, select Memory. This value is in 2K pages (thus, the value 
shown times 2 equals the number of kilobytes of memory allocated to SQL Server). 
SilverStream recommends the following formula: (system memory in megabytes / 2) 
* 512 = number of 2K pages to allocate to SQL Server. You must be logged in to SQL 
Server as SA or equivalent. SQL Server must be restarted to apply this change. 


NOTE Ifyou overallocate memory, SQL Server will not start. 


To create a Version 7 database: 


1. 


From SQL Server Enterprise Manager, right-click databases and select New Database 
and give the new database a name, such as SilverMaster. 


In File Properties, either allow for unrestricted file growth or allow at least 30 MB for the 
database. 


Select the Transaction Log tab and allow unrestricted file growth or allow at least 30 MB 
for the log file. 


Click OK to create the database. 


Select the TEMPDB and then right-click and select Properties. Verify that the 
unrestricted file growth is selected or that there is at least 50 MB allotted for it. 


Verify that you have the appropriate amount of memory allocated to SQL Server. This can 
be done through the SQL Enterprise Manager. 


Highlight the SQL Server, then right-click and select Properties. 
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8. On the SQL Server properties dialog, select the memory tab. 


9. Either verify that Dynamically configure SQL Server memory is selected or, if you are 
using a fixed amount of memory for SQL Server, subtract 64 MB from the total physical 
RAM in the machine and allocate this amount to the SQL Server (if the machine is only 
running SQL Server). If other server applications are also running on the machine 
(SilverStream, MS Exchange, and so on), you must also subtract the amount of memory 
needed for those applications. 


Create the SilverUser login 


Create a login called SilverUserLogin. 
Note the following: 


e The login cannot have a null password. 


e Set the default database for this login to the SilverMaster database you just created. If you 
do not, you receive error messages during the SilverStream Server Startup stating The 
database schema for SilverMaster is out of sync. 


e For SQL Server 6.5, you must alias this account to DBO for the SilverMaster database. 
For SQL Server 7, create a login using a SQL Server authentication mode and enable the 
db_owner role for the desired database on the Database Access tab. 


e The SilverUserLogin must have the following permissions: Create Table, Create View, 
Create SP, Create Default, Create Rule, Backup DB, and Backup Log. 


Setting up JDBC access 


The SilverStream server can connect to Microsoft SQL Server using the JDBC driver supplied 
by Microsoft. 


Install the JDBC driver 


You must have the Microsoft SQL Server JDBC driver installed on the PC where the 
SilverStream server will be. It must be able to connect to the destination SQL Server database. 
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Add the driver path to AGCLASSPATH 


The location of the Microsoft SQL Server JDBC driver (JAR files msbase.jar, mssqlserver.jar, 
and msutil.jar) must be specified in the AGCLASSPATH variable. For Windows, 
AGCLASSPATH is a system environment variable. For UNIX, you’ll find it in the .agprofile 
file. 


LL) For details, see the chapter on data source configuration in the Administrator’s Guide. 


Setting up ODBC access 


The SilverStream server can connect to Microsoft SQL Server using the ODBC driver supplied 
by Microsoft as part of the SQL Server client. There are different versions of this ODBC driver. 


Install the Microsoft SQL Server client 


You must have the Microsoft SQL Server client software installed on the PC where the 
SilverStream server will be. Your client must be configured to connect to the destination SQL 
Server database. 


Create the ODBC System DSN entry 


> To create the ODBC System DSN for a Version 6.5 database: 
Configure an ODBC System DSN entry for the SilverMaster or application database. 


Add an entry using SQL Server as the driver type. 


1 
2 
3. Enter the appropriate server name for the target SQL Server. 
4. Enter the destination database in the Default Database field. 
5 


Click the Options button and deselect the Create temporary stored procedures for 
prepared SQL statements and drop the stored procedures check box for use with the 
SilverStream server. 


If you do not deselect this option, the SilverStream server will not function properly with 
the database. 


> To create the ODBC System DSN for a Version 7 database: 
1. Add an entry using SQL Server as the driver type. 


2. Enter the server name for the target SQL Server. 
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3. Enter the SQL Server user authentication information for the SilverUserLogin and click 
Next. 


Select the proper default database name. 
Deselect Use ANSI quoted identifiers. 
Deselect Use ANSI nulls, paddings, and warnings and click Next. 


De he 


Accept the proper language and region settings, then click Finish. 


Using the database with the SilverStream server 


Now you’ re ready to access the Microsoft SQL Server database from the SilverStream server. 
This enables you to do any of the following, as appropriate: 


e Install the SilverStream server and point to that database as the SilverMaster (as 
described in Chapter 2, “Installing the SilverStream Server on Windows” and Chapter 3, 
“Installing the SilverStream Server on UNIX”) 


e Add that database to the SilverStream server for use as an application database 
e Adda connection pool to the SilverStream server for accessing that database 


LL) For more information, see the chapter on data source configuration in the Administrator’s 
Guide. 





Using the database with the SilverStream server 79 


9 Configuring Microsoft SQL Server Databases 








80 


Using the database with the SilverStream server 


1 0 Configuring Oracle Databases 





This chapter describes how to configure your Oracle database for use with the SilverStream 
eXtend Application Server as a SilverMaster or as an application database. 


LL) For the latest information on supported database versions, see the Release Notes. In 
Windows, you can access the Release Notes from the SilverStream eXtend program group or 
from the server’s Core Help. 


This chapter includes these sections: 


e Basic setup for Oracle databases 

e Setting up an Oracle driver 

e Using the database with the SilverStream server 
e Using synonyms 


e Troubleshooting 


Basic setup for Oracle databases 


You'll perform the following setup steps no matter which driver your SilverStream server will 
use to access an Oracle database: 


1. Create an Oracle tablespace for use with SilverMaster. 


2. Create an Oracle user for the SilverStream server. 


Create an Oracle tablespace for use with SilverMaster 


Creating a new Oracle tablespace for use with SilverMaster ensures optimal performance and 
ease of installation. To create one, run SQL Plus and connect to Oracle as System or SYSDBA. 


For example, this statement creates a tablespace with an initial size of 30 MB. 


CREATE TABLESPACE SilverTablespace 
DATAFILE ‘c:\databases\silvertablespace.dbf’ SIZE 30M; 


You can issue this statement from a SQL Plus prompt. If you choose to use an existing 
tablespace, make sure there is enough space available. 
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Create an Oracle user for the SilverStream server 


Setting 


To connect the SilverStream server to Oracle, create a new Oracle user for exclusive use by 
SilverStream. This user will own the SilverMaster tables. 


Issue the following statements using the SQL Plus utility. These statements create the user and 
set the user’s privileges. 


CREATE USER smuser IDENTIFIED BY password 
DEFAULT TABLESPACE SilverTablespace 

QUOTA UNLIMITED ON SilverTablespace; 
GRANT CONNECT, RESOURCE to smuser; 

REVOKE UNLIMITED TABLESPACE from smuser; 








up an Oracle driver 


The SilverStream server connects to Oracle databases using one of the following drivers: 


e Oracle Thin JDBC Driver 

e Oracle OCI Driver 

e A Type 2 JDBC driver written by and provided by SilverStream (this driver interfaces 
with the Oracle SQL Net Client to achieve connectivity to the Oracle Server) 


LL) See the SilverStream Release Notes for which versions of Oracle databases you can use 
with which drivers. 


Using the Oracle Thin JDBC Driver 


The SilverStream server can connect to Oracle databases using the thin JDBC driver supplied 
by Oracle. 


Install the driver 


You must have the Oracle Thin JDBC Driver installed on the PC where the SilverStream server 
will be. It must be able to connect to the destination Oracle database. 
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Add the driver path to AGCLASSPATH 


The location of the Oracle Thin JDBC Driver (for example, DriverPath/classes12.zip and 
DriverPath/nls_charset12.zip) must be specified in the AGCLASSPATH variable. For 
Windows, AGCLASSPATH is a system environment variable. For UNIX, you’ find it in the 
.agprofile file. 


LL) For details, see the chapter on data source configuration in the Administrator’s Guide. 


Using the Oracle OCI Driver 


The SilverStream server can connect to Oracle 9i databases using the OCI driver supplied by 
Oracle. 


Install the driver 


You must have the Oracle OCI Driver installed on the PC where the SilverStream server will be. 
It must be able to connect to the destination Oracle database. 


Add the driver path to AGCLASSPATH 


The location of the Oracle OCI Driver (for example, DriverPath/classes12.zip and 
DriverPath/nls_charset12.zip) must be specified in the AGCLASSPATH variable. For 
Windows, AGCLASSPATH is a system environment variable. For UNIX, you’ ll find it in the 
.agprofile file. 


LL) For details, see the chapter on data source configuration in the Administrator’s Guide. 


Using the SilverStream driver 


The SilverStream server can connect to Oracle databases using the Type 2 JDBC driver supplied 
by SilverStream. Setup involves these steps: 


1. Install the Oracle SQL Net client onto the machine where the SilverStream server resides. 


2. Create a SQL Net Alias for use by the SilverStream server. 





Setting up an Oracle driver 83 





10 Configuring Oracle Databases 





Install Oracle SQL Net Client 


If Version 2.3.4.0.0 of the Oracle SQL Net Client is not installed on the SilverStream server 
machine, install it now before you continue. If you do not have this version of SQL Net, obtain 
it from Oracle Corporation. Using the Oracle CD, follow the steps to install the client for an 
application user. 


If you already have the client installed, you can run Oracle Installer (from the Oracle for 
Windows NT Program Folder) to determine the version of SQL Net that is installed. 


Create an Oracle SQL Net Alias 


In order to connect to the Oracle server, you must have a valid Oracle SQL Net Alias that 
references the target Oracle server. 


> To create an Oracle SQL Net Alias: 


1. 


BS OY oe 


Run SQL Net Easy Configuration from the Oracle for Windows NT Program Group. 
NOTE On UNIX, run net8wiz.sh from the $ORACLE_HOME/bin/ directory. 
Choose Add a New Database Alias. 


Enter the name of the alias (you specified this name during the SilverStream server 
installation). 


A suggested name for this alias is SilverMasterORCL. 

Choose TCP/IP as the protocol and select OK to continue. 

Enter the TCP/IP Host Name for the Oracle Server and enter the correct Instance name. 
Choose OK to continue. 


Choose Yes to create the new alias. At this point you can exit the SQL Net Easy 
Configuration utility. 


Test the newly created SQL Net Alias by using SQL Plus to connect to the Oracle 
database server. 





84 


Setting up an Oracle driver 





eXtend Application Server Installation Guide 





Using the database with the SilverStream server 


Now you’re ready to access the Oracle database from the SilverStream server. This enables you 
to do any of the following, as appropriate: 


e Install the SilverStream server and point to that database as the SilverMaster (as 
described in Chapter 2, “Installing the SilverStream Server on Windows” and Chapter 3, 
“Installing the SilverStream Server on UNIX”) 


e Add that database to the SilverStream server for use as an application database 
e Adda connection pool to the SilverStream server for accessing that database 


LL) For more information, see the chapter on data source configuration in the Administrator’s 
Guide. 


Creating a SilverStream application database on Oracle 


Adding an Oracle database to SilverStream equates to adding an Oracle user. Adding a database 
does two things: 


e — Adds all the tables and views that the database user has access to (application tables) 


e Creates SilverStream system tables to store metadata 
Before adding Oracle databases 


Storing system tables separately 


If you want to store the SilverStream system tables in a separate database account, create an 
additional database user as described above and, if using the SilverStream driver, create a new 
Oracle SQL Net Alias. SilverStream system tables may also be stored in any other databases 
supported by SilverStream. 


Using a different character set 


You can tell the SilverStream Oracle 8 driver to use a different character set than what is 
specified in the Oracle instance. You would do this when the character set encoding of the data 
is different than the character set specified by the Oracle instance. For more information on this 
topic, go to the Members Support area on http://www.silverstream.com. A document on the 
subject can be found in the knowledgebase under White Papers, Oracle. 
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Adding a database 


Specifying the database if using the SilverStream or OCI driver 


When adding an Oracle database to SilverStream, you are asked for the name of the database. If 
you are using the SilverStream or OCI driver, the database name refers to the Oracle SQLNet 
Alias or TNSNAMES.ORA entry. The SQLNet Alias points to a specific Oracle Database 
Instance on a specific server. Typically you have one per Oracle database. 


The SilverStream server requires a unique database name. This means that the SilverStream 
server requires you to create a unique SQLNet Alias for each Oracle database user you add. So 
if you have SilverMaster, application tables, and the SilverStream system tables stored in three 
different Oracle database users, you need three unique SQLNet Aliases—one for each user. 
Each SQLNet Alias points to the same Oracle database. 


LL) Optionally, if you do not want to configure multiple SQLNet Aliases, see “Using one 
SQLNet Alias” on page 87. 


Oracle 8i notes 


Using databases containing periods in their names When using Oracle 8i, you 
cannot use a database name that contains a period. You can successfully add a database with a 
period in the name, but later interactions between the SilverStream server and the database will 
result in NullPointer Exception errors and other unwanted behavior. 


If you are using the SilverStream driver, the tnsnames.ora entry is of the form 
myalias.domain.com. On Windows, it is sufficient to specify only myalias for the database name 
when adding a database to the SilverStream server and the connection to the database will be 
successful. But on most UNIX platforms this truncated specification will not succeed in a match 
for the entry in tnsnames.ora. When you add the database to the SilverStream server it will result 
in the error TNS names entry not found. 


Verifying your connection The SilverStream server’s database connection behavior is 
consistent with that of SQLPlus. The best way to troubleshoot your connection to Oracle 81 is to 
first verify the connection through SQLPlus. Be sure to connect only to myalias as that is what 
is needed for the SilverStream server. 


For example, try to connect using sqlplus login/password @myalias rather than sqlplus 
login/password @ myalias.domain.com. 


If your connection to myalias does not succeed using SQLPlus, then you may need to edit the 
tnsnames.ora entry and remove the domain.com from the entry. 
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Using one SQLNet Alias 


This is an optional advanced feature if you are using the SilverStream or OCI driver. By default, 
the Add Database process assumes you are adding an Oracle database with a separate SQLNet 
Alias (TNS NAME) for each Oracle database user that you use in the SilverStream 
environment. 


The steps that follow are for experienced users. They document how you can install using a 
single SQLNet Alias. 


> To install using a single SQLNet Alias: 
1. When adding a new database to the SilverStream server, do not enter the SQLNet Alias 
(TNS NAME) in the database name box; enter any name you want. 


2. Now enter the user name and password as before and select Oracle 7 or Oracle 8 as the 
database platform. 


3. Choose User-specified JDBC driver for the driver set. 
4. Click Next. 
You can now enter the JDBC connection string. 
5. For the JDBC URL, enter: 
jdbc:sssw:oracle: TNSNAME 
replacing TNSNAME with the TNS NAME in your TNSNAMES.ORA file. 


You can now connect as many databases as you like using the same TNS NAME. Make sure you 
store the system tables separately. 


What to avoid You can reduce the chance of encountering problems if you follow these 
rules: 


e Do not put anything else in the same Oracle database user as your SilverMaster. 


e Do not put multiple system tables in the same Oracle database user. These would conflict 
with each other. When adding multiple databases to the SilverStream server, you should 
keep their system tables separate. 
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Terminology differences Different databases use different terminology. The SilverStream 
terminology might be confusing for Oracle users. For example, SilverStream database means 
Oracle database user. SilverStream uses the word databases, but on Oracle these map to 
Oracle database users. The following table describes other differences. 











SilverStream term Oracle term 
SilverMaster database Oracle database user that owns the SilverMaster tables 
Add a database Add a specific user in an Oracle database 














Using synonyms 
The SilverStream server provides support for Oracle 8 and later synonyms for tables and views. 


NOTE With Oracle, you can also define synonyms for other kinds of objects, including object 
tables, object views, and stored procedures. The SilverStream server supports 
synonyms only for tables and views. 


Specifying the driver In order to enable synonym support, you need to specify one of the 
following driver sets when adding the Oracle database to the SilverStream server: 


¢ Thin Oracle JDBC driver with synonym/mixed case support—Oracle’s thin JDBC 
driver with synonym support 


e OCI Oracle JDBC driver with synonym/mixed case support—Oracle’s OCI driver 
with synonym support 


e SilverStream JDBC driver with synonym/mixed case support—SilverStream’s Oracle 
8 driver with synonym support 


Once you have chosen one of these driver sets for an Oracle database, synonyms defined for 
tables and views are displayed in the SilverStream Designer’s list of tables (Classic Edition 
only), as long as you have access to the synonyms, as described next. 


Types of synonyms = Synonyms can be either private or public. A public synonym is 
owned by the special user group PUBLIC; every user of a database can access it. 


A private synonym is in the schema of a specific user, who has control over its availability to 
others (see Oracle’s Oracle 8 Concepts manual). Individual users can see only the public 
synonyms and their own private synonyms. 
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How synonyms behave A synonym that displays in the table list behaves exactly like its 
underlying table or view—because support for synonyms is built into the JOBC method calls, 
which access the underlying tables and views to retrieve the required information. 


The following JDBC implementation methods have synonym support built in: getTables, 
getTableTypes, getTablePrivileges, getColumnPrivileges, getPrimaryKeys, getImportedKeys, 
getExportedKeys, getCrossReference, and getIndexInfo. 


Enabling and disabling synonym support There is a property called 
includeSynonyms in the platforms.dbl file in the SilverStreamInstallDir/Resources directory 
that specifies whether a driver supports synonyms. The property is in the PROPERTIES section 
for the driver. 


DRIVER 

/Name ... 
/JdbcDriver ... 
/DriverSet ... 


PROPERTIES 
/includeSynonyms "true" 


If you want to use one of these drivers but want synonym support disabled, set the 
includeSynonyms property to false. Similarly, if you have written your own Oracle driver and 
have implemented synonym support, to enable the support you need to set the 
includeSynonyms property to true in the PROPERTIES section for your driver. 


Troubleshooting 


This section describes the most common errors and workarounds if available. 


ORA-01019 “unable to allocate memory in the user side” If you receive this 
message while running with a Net8 Oracle Client, free up available memory on the machine 
where the SilverStream server is installed. 


ORA-01460 “unimplemented or unreasonable conversion requested” If you 
receive this message when SilverMasterInit is creating an Oracle SilverMaster or when you are 
attempting to add an Oracle database to your SilverStream server, you must upgrade to at least 
Version 8.0.4 of the Oracle client software. This problem occurs on versions before 8.0.4. 
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ORA-01631, 00000, “max # extents (%s) reached in table %s.%s” This message is 
caused when a table tried to extend past maxextents. To solve this problem, check your 
INITIAL, NEXT, and PCTINCREASE parameters on the DEFAULT TABLESPACE for the 
SilverMaster user. You must get your DBA to increase them. For example: 


SELECT DEFAULT TABLESPACE 

FROM dba_users 

WHERE username = 'MYUSER'; 

SELECT * 

FROM dba_tablespaces 

WHERE tablespace name = 'MYTABLESPACE' ; 

ALTER TABLESPACE MYTABLESPACE 

DEFAULT STORAGE (INITIAL 10K, NEXT 10K, PCTINCREASE 50); 











ORA-01950, 00000, “no privileges on tablespace '%s'” This message is caused 
when a user does not have privileges to allocate an extent in the specified tablespace. To solve 
this problem, grant QUOTA to the user on the mentioned database. For example: 


ALTER USER MYUSER 
QUOTA UNLIMITED ON MYTABLESPACE; 


TNS-12154 "TNS: could not resolve service name" If you receive this message, you 
must verify that you have correctly created the SQL Net Alias as described in “Create an Oracle 
SQL Net Alias” on page 84. 


Tablespaces for Oracle databases The installation will use the default tablespace of the 
user name/password specified for your SilverMaster database. You can usually set the default 
tablespace with the following SQL statement: 


ALTER USER username DEFAULT TABLESPACE mytablespace ; 


Adding large numbers of tables If you are planning to connect SilverStream to a large 
Oracle tablespace, open the SilverStream Management Console (SMC) and change the value of 
the timeout for server requests to 30,000 seconds. 


You must modify this value before attempting to add any large Oracle application. Once the 
application has been added successfully, reset the value back to the default value (3,000). The 
SilverStream server must be restarted for these changes to be applied. 


LL) For more information, see the section on setting performance parameters in the 
Administrator’s Guide. 


Using different database types with the same SilverStream server If you install 
with a non-Oracle SilverMaster and want to add an Oracle database, you need to have 
$ORACLE_HOME set and have $ORACLE_HOME/lib in your SHLIB_PATH (for HP-UX), 
LD_LIBRARY_PATH (for Solaris and Linux), or LIBPATH (for AIX). 
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Adding an Oracle 8i database on Solaris On Solaris, if you are not using an Oracle 8i 
database as your SilverMaster but are using Oracle 8i client software and want to add an Oracle 
8i database to your server, you must copy a library file in the $SILVERSTREAM/bin directory. 
By default, the installed Oracle driver library file is appropriate for Oracle 8. 


The following procedure will allow you to use the Oracle 8i library file instead: 


1. Back up the libagora8_jni.so file: 


# cd SSILVERSTREAM/bin 
# cp libagora8_jni.so libagora8_jni.so.orig 


2. Copy the Oracle 8i driver library file: 


# cp libagora8_jni.so.8i libagora8_jni.so 


Connecting to Oracle from HP-UX or AIX If you are using the SilverStream driver, in 
order to connect to an Oracle database from HP-UX or AIX, you must have at least the 
following Oracle components installed on the HP-UX or AIX machine: 

e Net8 

e  Net8 External Naming Adapters 

e  Net8 Protocol Adapters 

e Oracle Intelligent Agent 

e PL/SQL 

e SQL*Plus 

In addition, during the Oracle installation process you will be asked if you want to relink Oracle 
product executables. You must answer yes. By default, the relinking will not occur. 

If the Oracle installation is not sufficient for the SilverStream server, you will get the following 
error during SilverMasterInit: 


/usr/lib/dld.sl: Unresolved symbol: opinit (code) from 
/home/username/silverstream/bin/libagora_jni.sl 


If you encounter this error or another type of connection error, verify that you have installed the 
Oracle components listed above and can connect to your database using SQL*Plus. 
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1 1 Configuring Sybase Adaptive Server Anywhere 
Databases 





This chapter describes how to configure your Sybase Adaptive Server Anywhere (ASA) 
database for use with the SilverStream eXtend Application Server as either a SilverMaster 
database or an application database. 


LL) For the latest information on supported database versions, see the Release Notes. In 
Windows, you can access the Release Notes from the SilverStream eXtend program group or 
from the server’s Core Help. 


This chapter includes these sections: 


e Overview of Sybase ASA support 
e Setting up a Sybase ASA database 
e Using ASA 6 and ASA 8 on the same machine 


Overview of Sybase ASA support 


SilverStream eXtend Application Server Classic and Developer editions include a special 
authenticated edition of Sybase ASA Version 8. Because this edition is authenticated, it can be 
used only with the SilverStream server. 


This authenticated edition of Sybase ASA allows users who do not already use Sybase ASA to 
install it at the same time they install the SilverStream server. This software is supplied in part 
because the classic SilverStream sample applications are stored in Sybase ASA databases. If 
you already have Sybase ASA installed, you do not need to install this authenticated version. 


You can use Sybase ASA as your SilverMaster and as your application databases. You can use 
the authenticated version provided with the SilverStream server or the full version purchased 
from Sybase. 


For upgraders Earlier versions of the SilverStream server included authenticated editions 
of earlier Sybase ASA versions. SilverStream server support for versions 5 and 6 of ASA has 
been deprecated in Version 4. Using these earlier versions of ASA with Version 4 of the server 
should work, but we recommend that you upgrade these databases to the currently supported 
versions by using the Sybase Central Upgrade Database utility. 


LI For more information, see the Sybase Central online help. 





93 





11 Configuring Sybase Adaptive Server Anywhere Databases 





Setting up a Sybase ASA database 
This section describes how to set up Sybase ASA databases to use with the SilverStream server. 


You can install the authenticated version of Sybase ASA from the SilverStream server 
installation program, which launches the Sybase SQL Anywhere Studio installation program. 
You can follow the Sybase wizard and choose all the defaults to install ASA for use with the 
SilverStream server. 


Setup choices The SilverStream server connects to Sybase ASA using either ODBC or 
jConnect (Sybase’s JDBC driver). The Sybase ODBC driver and jConnect are included as part 
of the Sybase ASA installation. 


e To use Sybase ASA for your SilverMaster, all you need to do is install Sybase ASA 
before installing the SilverStream server. 
When you install the SilverStream server (as described in Chapter 2, “Installing the 
SilverStream Server on Windows’), specify that you want to use Sybase ASA as your 
SilverMaster. The SilverStream installation program will create and configure the 
SilverMaster database for you (if you ask it to). It will create and use an ODBC 
connection. 


e To use Sybase ASA for an application database, you need to set up the database 
yourself as described in the next section. When you add the database to the SilverStream 
server, you specify whether you want to use ODBC or jConnect. 


This also applies if you want to access a Sybase ASA database by adding a connection 
pool to the SilverStream server. 


LL) For more information on setting up SilverMaster, application databases, and connection 
pools, see the chapter on data source configuration in the Administrator’s Guide. 


Using jConnect Although you can connect to an ASA database using either ODBC or 
jConnect, the SilverStream ODBC-JDBC bridge is deprecated in Version 4; so we recommend 
that you use jConnect. 


The jConnect driver is included with ASA. When you install ASA using the Sybase wizard, the 
driver is installed in the Sybase Shared directory. To use jConnect, you need to do this one-time 
setup: 


e Set AGCLASSPATH (environment variable for the server’s classpath) on the machine 
where your SilverStream server is running to include the path to the jConnect 5.5 driver: 


AGCLASSPATH=SybaseInstallDir\Shared\jConnect-5 5\classes\jconn2.jar 
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For example, if you installed ASA in the default location, you would specify this in 
AGCLASSPATH: 


AGCLASSPATH=c:\Program Files\Sybase\Shared\jConnect - 
5_5\classes\jconn2.jar 


LI For more information on listing JDBC driver JARs via AGCLASSPATH, see the 
chapter on data source configuration in the Administrator's Guide. 


Setting up application databases To set up a Sybase ASA database as an application 
database, do the following: 

1. Create a database. 

2. Create a user account to be used by the SilverStream server. 


3. If you are using ODBC for the database connection, create an ODBC System DSN entry 
for the database. 


4. Configure Sybase ASA to run as a service. 


5. Make the database available to the SilverStream server. 


The following sections describe these steps. 


Step 1: Create a database 


If you want to use an ASA database as your SilverMaster, you can have the server installation 
program create a database when you install the server (or you can point the installation program 
to an existing ASA database). If you want to use an ASA database as an application database, 

you create it before adding it to the server. 


Use Sybase Central to create the database. 


LI For more information, see the Sybase Central online help. 


Step 2: Create user accounts 


Sybase ASA provides a default user dba with the password sql. You can use this user name and 
password pair for your SilverMaster database or any other Sybase ASA database. 


However, we strongly recommend that you set up separate accounts for your SilverMaster and 
for each application database; this way you can easily tell which applications are hitting your 
database when and how often, and you can more easily troubleshoot performance problems. 
Make sure this account has at least Resource and Connect privileges. 


LL) For more information about setting up user accounts, see the Sybase Central online help. 
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Step 3: (Optional) Create the ODBC System DSN entry 


If you will be connecting to the database using ODBC, you need to create an ODBC entry for 
the database. 


LL) For more information, see Appendix A, “Creating ODBC Data Sources”. 


Step 4: Run Sybase ASA as a service 


We recommend that you run your Sybase ASA databases as a service to make database use and 
maintenance easier. This is especially true with jConnect since it does not have the autostart 
capability of ODBC. 


LL) For information about running Sybase ASA as a service, see the Sybase ASA online help. 
(In that help, select ASA Database Administration Guide. Go to “Running the server outside the 
current session” in Chapter 1.) 


Step 5: Make the database available to the server 


If you’re using an ASA database as your SilverMaster, you either have the server installation 
program create a new database, or you point the installation program to an existing database. If 
you’re using an ASA database as an application database, you can make the database available 
by adding it to the server: 


1. If you are connecting with jConnect, make sure the database is running. If it is not running 
as a service, you can start it using Sybase Central. 
2. Using the SMC, add the database to the server. 


e Ifusing ODBC, specify the name of the ODBC profile and the user name and 
password. The server will start the database if necessary. 


e  Ifusing jConnect, specify the name of the database, the user name and password, and 
the JDBC URL for the database, which has the following format: 


jdbc:sybase:Tds: hostname: port ?SERVICENAME=dbname 


For example, if your database is named MyDB and you are running it locally at the 
default ASA port of 2638, your JDBC URL would be: 


jdbc:sybase:Tds:localhost :2638?SERVICENAME=MyDB 


Instead of adding a database to the server, you can make a database available to the server by 
defining a JDBC connection pool for it. 


LL) For more information on adding databases to the server and defining connection pools, 
see the chapter on data source configuration in the Administrator’s Guide. 
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Using ASA 6 and ASA 8 on the same machine 


It’s possible to have both Sybase ASA Version 6 and Version 8 installed on a machine. The 
typical scenario is that you already have ASA 6 and are adding ASA 8 to begin upgrading your 
databases. 


To avoid conflicts between the two versions, you should follow these steps when setting them 


up: 
1. 


When installing ASA 6 or 8, make sure you start from the SilverStream server’s 
installation program. 

Choose Install software, then Install Sybase Adaptive Server Anywhere... This ensures 
that your installation of ASA 6 or 8 is authenticated. 

Install the two versions of ASA (including the Shared directory and the Sybase Central 
directory) on separate directory paths. 

Once you’ ve installed ASA 6 then ASA 8, check your system’s Path environment 
variable. Make sure the ASA 8 directories are listed after those for ASA 6. 

Run Sybase Central 4.1 from the ASA 8 program group. Confirm that you can create a 
database and open it. 

Run Sybase Central 3.2 from the ASA 6 program group. 

You'll probably see that there are no Plug-ins available. To add the ASA 6 Plug-in back, 
open the Plug-ins dialog (Tools>Plug-ins). Then click the Change button and check the 
Adaptive Server Anywhere option. This should re-register the proper Plug-in for ASA 6 
(so you can use Sybase Central 3.2 to create and inspect ASA 6 databases). 


Running as a service If you’re going to run your ASA 6 and 8 databases as a service, 
make sure you specify the following during the service setup: 


The database name, useful for jConnect access (since the database won’t autostart). 


The tcpip port parameter, needed to specify a different port for ASA 6 and 8 so they 
won’t both try to use port 2638. For instance, you might set ASA 8 to port 22222. 
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This chapter describes how to use Sybase Adaptive Server Enterprise databases with the 
SilverStream eXtend Application Server. It includes information about using Adaptive Server 
Enterprise as a SilverMaster database or as an application database. 


NOTE Sybase Adaptive Server Enterprise was formerly known as Sybase SQL Server. 


LL) For the latest information on supported database versions, see the Release Notes. In 
Windows, you can access the Release Notes from the SilverStream eXtend program group or 
from the server’s Core Help. 


This chapter includes these sections: 


e Setting up Sybase Adaptive Server Enterprise databases 


e Troubleshooting 


up Sybase Adaptive Server Enterprise databases 


This section describes how to create a SilverMaster database using Sybase Adaptive Server 
Enterprise. You must install the Sybase client onto the machine where the SilverStream server 
resides. Once you have done that, the remaining steps include: 

Install the Sybase jConnect classes and stored procedures. 

Configure the Sybase server. 

Create database devices and the actual SilverMaster database as a Sybase database. 


Create a database login to be used by the SilverStream server. 


Sus a NY 


Use the database with the SilverStream server. 


Step 1: Install Sybase jConnect 


You must install and configure the jConnect driver on the machine where you will be installing 
the SilverStream server. This driver must be configured before you install the SilverStream 
server. 


NOTE SilverStream recommends that you use jConnect 5.x. 
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> To install Sybase jConnect: 


1. 


Install the jConnect driver. 
LL) For more information about Sybase jConnect, see http://www.sybase.com/products. 


Make sure the location of the jConnect driver is specified in the AGCLASSPATH variable 
on your SilverStream server machine. For Windows, AGCLASSPATH is a system 
environment variable. For UNIX, you’ll find it in the .agprofile file. 
If you are using jConnect 4: 

AGCLASSPATH=installDir\jConnect-version\classes 


If you are using jConnect 5: 





AGCLASSPATH=installDir\jConnect-version\classes\jconn2.jar 
LL) For more information on listing JDBC driver files via AGCLASSPATH, see the 
chapter on data source configuration in the Administrator's Guide. 
NOTE You do not need to configure the CLASSPATH or JOBC_HOME variables 


mentioned in the Sybase installation notes if you are using the driver exclusively 
with the SilverStream server. 


Install the jConnect stored procedures onto the Sybase server. 


LL) For more information, see Sybase’s jConnect for JDBC Installation Guide or 
http://www.sybase.com/products. 


Step 2: Configure the Sybase server 


You must configure the Sybase server to support the SilverStream server. These configuration 
changes involve sizing your Sybase TEMPDB database appropriately and configuring the 
correct amount of Sybase procedure cache to support the jConnect stored procedures. 


> To configure the Sybase server: 


1 


From Sybase Central, connect to the destination Sybase server and select Databases. 
You need to connect to the Sybase server as SA or an equivalent. 

Right-click the TEMPDB database and select Properties. 

From the Usage tab, check the Total Allocated value. 

If the TEMPDB Total Allocated value is less than 30 MB: 


e Create a new 30 MB database device (from within the Database Devices folder) called 
TempExtend. 
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e When this process completes, right-click the TEMPDB database (from within the 
Databases folder). 

e From the Devices tab, add the new TempExtend device as a DATA device. 

Right-click the Sybase server and select Configure. 

Scroll down until you see the value Total Memory. 

The value for total memory is in 2K pages, so the numeric value shown times 2 equals the 

amount of memory (in kilobytes) currently allocated to Sybase. Take note of this value 


and then find the value Procedure Cache Percent. This value should be the percentage 
equivalent to 13 MB of memory. 

To find this value, divide 13,000 by the Total Memory amount (in kilobytes). This will 
give you the percentage that you should enter in the Procedure Cache Percent value. 


For example, the default amount of memory allocated to Sybase Adaptive Server 
Enterprise 11.5 is 9000 pages (equivalent to 18,000 kilobytes). If you divide 13,000 by 
18,000, the value for Procedure Cache Percent equals .72 or 72%. Enter 72 as the new 
value for the Procedure Cache Percent. 


Restart the Sybase server for the change to take effect. 


Step 3: Create the SilverMaster database in Sybase 


Before you can install the SilverStream server, you must first create the actual Sybase database 
(and its underlying database devices). You can create these objects using either ISQL or a 
graphical tool such as Sybase Central. The following procedure describes how to use Sybase 
Central to create the objects. 


> To create the SilverMaster database: 


1. 
2. 


Connect to Sybase using SA or an account with SA equivalence. 


From Sybase Central, connect to the destination Sybase server and select Database 
Devices. 


Create a new 30 MB database device called SilverMasterData. 
When this process completes, create another new 30 MB device called SilverMasterLog. 


From the Databases folder in Sybase Central, create a new database called silvermaster 
(this is case sensitive). 


Create the database using the two devices that you created above using all 30 MBs of each 
respective device for data and for log. 


Once the database has been created, right-click the database and select Properties. 
From the Options tab, select Truncate Log on Checkpoint. 
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Step 4: Create the Sybase login for the SilverStream server 


Once the jConnect driver is installed and the SilverMaster database has been created, you must 
create a Sybase login for use by the SilverStream server. 


To create the Sybase login: 


1. From Sybase Central, connect to Sybase using SA or an account with SA equivalence. 


2. From the Login folder, add a new Login (for example, you could call it smuser). You must 
assign this account a password of at least six characters. 


3. Set the default database for this login to silvermaster and complete the login creation 
process. 


4. From the Databases folder, right-click the silvermaster database and select Properties. 


5. Click the Change button to change the owner of the database from SA to the smuser 
login. 


You also need to define logins for each application database you will use. The user must have a 
minimum of SELECT permission against all of the tables in the desired Sybase database (you 
will need UPDATE and DELETE permissions if your SilverStream application supports these 
data manipulation operations). 


This user account must also have CREATE TABLE permission if you are going to store 
SilverStream system tables in the application database (this is the default behavior for 
application databases that you add to the server). 


Step 5: Use the database with the SilverStream server 


Now you’ re ready to access the Sybase Adaptive Server Enterprise database from the 
SilverStream server. This enables you to do any of the following, as appropriate: 


e Install the SilverStream server and point to that database as the SilverMaster (as 
described in Chapter 2, “Installing the SilverStream Server on Windows” and Chapter 3, 
“Installing the SilverStream Server on UNIX”) 


e Adda database to the SilverStream server for use as an application database 
e Adda connection pool to the SilverStream server for accessing a database 


LL) For more information, see the chapter on data source configuration in the Administrator’s 
Guide. 
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Troubleshooting 


Sybase Adaptive Server Enterprise troubleshooting 


This section describes the known problems and workarounds for Sybase Adaptive Server 
Enterprise databases with the SilverStream eXtend Application Server. 


JZ0CO errors You may receive error messages from jConnect with an error code of JZ0CO 
and the error message Connection already closed. If you receive this error, verify that you are 
running Sybase server Version 11.0.3.2. If your Sybase version is not 11.0.3.2, obtain the 
updates through Sybase technical support. 


If you cannot update your Sybase server version, separate your SilverStream system tables from 
the Sybase database to work around the problem. 


Logins, users, and permissions The easiest way to avoid potential problems with 
logins, users, and permissions is to use sa. If problems occur while adding a database, 
SilverStream Technical Support may ask you to try adding the database as sa to determine if the 
problem is with logins, users, or permissions. 


However, in many environments it is not practical to obtain the sa password. The following 
SQL examples show you how to create a login and user with the correct permissions for the 
SilverStream server. 


e Login The login defines access to an Adaptive Server Enterprise database, as well as the 
default database and password. Use this SQL script to create a login called SilverUser: 


USE master 
go 
EXEC sp_addlogin SilverUser','PASSWORD', 'mydatabase', 
'us_english',"SilverUser" 
go 
e User A user defines a set of permissions for a particular database and is associated with 
a login. Use this SQL script to create a user called SilverUser: 


EXEC sp_adduser 'SilverUser','SilverUser','public' 
go 

GRANT CREATE TABLE TO SilverUser 

go 
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Primary keys and foreign keys The primary and foreign key of older databases (from 
Sybase System 10 and earlier) may still be defined using system stored procedures named 
sp_primarykey and sp_foreignkey. Sybase no longer recommends creating primary and 
foreign keys in this manner. In fact, their newer products, including jConnect, do not recognize 
primary and foreign keys created in this manner. You can determine if your database uses these 
stored procedures by examining the DDL used to create your database. 


Primary keys This is what the DDL will look like with an older-style primary key: 


CREATE TABLE dbo.U_LBX ADVICE 
( 
advice _key smallint NOT NULL, 
<PAYMENT_KEY file key smallint NOT NULL, 
batch_key smallint NOT NULL, 
line _no varchar(20) NULL, 
item_paid_id varchar(20) NULL, 
item_paid_amount money NULL 
) 
go 
EXEC sp primarykey 'dbo.U_LBX ADVICE', 
advice _key,payment_key,file_key,batch_key 























The newer Sybase Adaptive Server Enterprise format for creating primary keys is part of the 
CREATE TABLE syntax: 


create table U_LBX ADVICE 

( 

advice_key smallint not null, 
payment_key smallint not null, 
file _ key smallint not null, 

batch _key smallint not null, 

line _no varchar(20) null, 

item_paid_id varchar(20) null, 
item_paid_amount money null, 
constraint PK_U_LBX ADVICE primary key 
(advice_key, payment_key, file _key, batch_key) 


) 


If your table already exists and you cannot recreate the table with the CREATE TABLE 
statement, then use ALTER TABLE as shown below: 


ALTER TABLE dbo.U_LBX ADVICE ADD CONSTRAINT newprimarykey PRIMARY KEY 
NONCLUSTERED (advice_key,payment_key,file_key,batch_key) 
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Foreign keys Foreign keys define the relationship between tables. The problem with 
foreign keys is very similar to the one with primary keys described above: Sybase’s jConnect 
does not recognize foreign keys created in the older System 10 format using sp_foreignkey. This 
is the older style DDL that would be used to create foreign keys: 


exec sp _foreignkey dbo.U_LBX ADVICE, dbo.U_LBX BATCH, 
file key, 
batch_key 


The syntax for adding a similarly defined foreign key is: 


ALTER TABLE dbo.U_LBX ADVICE ADD CONSTRAINT myforeignkey FOREIGN KEY 
(file_key,batch_key) 

REFERENCES sqlfinarl.dbo.U_LBX BATCH (file key,batch_key) 

go 


You can use the Sybase PowerDesigner tool to update the DDL that creates a database to the 
newer format. To use this tool, follow these guidelines after backing up your database: 
1. From PowerDesigner’s menu, choose File/Reverse Engineering. 


2. Enter either the file containing your database’s DDL or the name of an ODBC driver to 
connect directly to your database. 


3. Choose Database/Generate Database to create a new DDL which will define primary 
and foreign keys with the correct syntax. 


4. As with any tool, double-check and test the new syntax for any possible omissions. 


jConnect troubleshooting 


If the jConnect stored procedures are not properly installed and the problem is not detected, then 
you can have problems adding a database. 
One way Do this to verify that jConnect is properly installed: 


e Open a DOS window and verify that your AGCLASSPATH environment variable points 
to your jConnect\classes directory. 
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Another way Another way to determine if jConnect is successfully installed is to try to run 
the sample jConnect applications (make sure you have installed the samples: check that a 
classes\sample directory exists). Type the following lines at a DOS prompt. 


e Ifyou are using jConnect 4, type the following: 
set CLASSPATH=installDir\jConnect-version\classes 
java sample.SybSample Validate -U sa -P password -S 
jdbc:sybase:Tds: servername: port 
e Ifyou are using jConnect 5, type the following: 
set CLASSPATH=installDir\jConnect-version\classes\jconn2.jar 


java sample2.SybSample Validate -U sa -P password -S 
jdbc:sybase:Tds: servername: port 


These commands will start an application that can launch a variety of sample jConnect 
applications by clicking File/Open Sample. 





106 


Troubleshooting 





A Creating ODBC Data Sources 





Certain databases must be set up as ODBC data sources. The following example shows you how 
to set up an ODBC data source in Windows for a Sybase Adaptive Server Anywhere database. 


NOTE When you install the SilverStream eXtend Application Server, ODBC data sources are 
defined for you automatically for the SilverMaster (if needed) and the classic sample 
applications. 


Creating an ODBC data source 


> To create an ODBC data source: 


1. Choose Settings from the Start menu. 
2. Select Control Panel. 
3. Select the Data Sources (ODBC) icon: 


ag 
[=] 
——] 
Data Sources 


(ODBC) 


4. Set up a System DSN so that everyone on the system can have access. Only the machine 
running the SilverStream server requires the database client software. Use the System 
DSN tab as shown in the following screen. 


€ ODBC Data Source Administrator | 24 x] 
UserDSN System DSN | File DSN | Drivers | Tracing | Connection Pooling | About | 


System Data Sources: 


CE a 7 


ti Adaptive Server Anywhere 6.0 
arene Adaptive Server Anywhere 8.0 
ClassicD ataXpress Adaptive Server Anywhere 8.0 
ClassicEjbExamples Adaptive Server Anywhere 8.0 
ClassicFormExamples Adaptive Server Anywhere 8.0 
ClassicPageExamples Adaptive Server Anywhere 8.0 
ClassicWebsite Adaptive Server Anywhere 8.0 
DataXpress37 Adaptive Server Anywhere 6.0 
Director Adaptive Server Anywhere 6.0 
Examples37_3GL Adaptive Server Anywhere 6.0 
Examoles3? EJB Adaptive Server Anywhere 6.0 zl 


Add... 


Remove | 
Configure... | 














the indicated data provider. A System data source is visible to all users 


E An ODBC System data source stores information about how to connect to 
on this machine, including NT services. 
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5. 


8. 


Choose Add. 


The Create New Data Source window displays. 


Create New Data Source Eg 


Select a driver for which you want to set up a data source. 


[Name | Version A 
Adaptive Server Anywhere 6.0 6.00.02.2188 
A Anywhere 8.0 8.00.00.206£ 
iånywhere Solutions 8 - Oracle 8, 8i& 9i 4.00.00.00 

iånywhere Solutions 8 - Sybase ASE 4.00.00.00 

Microsoft Access Driver (*.mdb] 4.00.6019.0f 
Microsoft dBase Driver (*.dbf] 4.00.6019.0¢ 
Microsoft Excel Driver (*.xls) 4.00.6019.0f 
Microsoft FoxPro Driver (*.dbf) 4.00.6019.0f 


Microsoft ODBC for Oracle 2.573.6013.( 5 
è Í 

















































hdicracoft Paradew Driver [* dh 1 ANN eno My 








Choose the appropriate driver. The rest of this example uses Sybase Adaptive Server 
Anywhere. 


Choose Finish. A configuration form appears: 


ODBC Configuration for Adaptive Server Anywhere 8 EG 


ODBC | Logn | Database | Network | Advanced | 


Data source name: | 
Description: | 


Isolation level: | 


T Microsoft applications (Keys in SQLStatistics) 





T Delphi applications 
I Prevent driver not capable errors 
T Delay AutoCommit until statement close 





Describe Cursor Behavior 
c Never © If required C Always | 





Translator: [No Translator> 
Select Translator... | 





Test Connection | 





On the ODBC tab, name the data source and optionally provide a description. 
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9. On the Database tab, enter the following information: 


NOTE Ifyou are setting up Adaptive Server Anywhere databases from a network server, 

you should follow the instructions provided by the network server. 

e Server name: If you want the database to use its own engine, specify the server name 
as the same as the data source name. If you want one engine to service more than one 
database, specify the name of an engine that is used by other databases. 

e Start line: Specify the engine for Adaptive Server Anywhere (default for Version 8: 
C:\Program Files\Sybase\SQL Anywhere 8\win32\dbeng8.exe). 

e Database name: The name of the database (not including the file extension). 

e Database file: The path and file name of the database. You can click Browse to browse 
for the database file. 

NOTE The default user name and password for an Adaptive Server Anywhere database 

are dba and sql. You can specify this information in the Login tab, or you can 
specify it when you add the database to the SilverStream server. 


10. Click OK. 


If you need help, look at the ODBC settings for the classic sample applications you installed 
with the SilverStream server. 
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